carb package#

class carb.ColorRgb#

property b#

property g#

property r#

class carb.ColorRgbDouble#

property b#

property g#

property r#

class carb.ColorRgba#

property a#

property b#

property g#

property r#

class carb.ColorRgbaDouble#

property a#

property b#

property g#

property r#

class carb.Double2#

property x#

property y#

class carb.Double3#

property x#

property y#

property z#

class carb.Double4#

property w#

property x#

property y#

property z#

class carb.Float2#

Pair of floating point values. These can be accessed via the named attributes, x & y, but also support sequence access, making them work where a list or tuple is expected.

>>> f = carb.Float2(1.0, 2.0)
>>> f[0]
1.0
>>> f.y
2.0

property x#

property y#

class carb.Float3#

A triplet of floating point values. These can be accessed via the named attributes, x, y & z, but also support sequence access, making them work where a list or tuple is expected.

>>> v = [1, 2, 3]
f = carb.Float3(v)
>>> f[0]
1.0
>>> f.y
2.0
>>> f[2]
3.0

property x#

property y#

property z#

class carb.Float4#

A quadruplet of floating point values. These can be accessed via the named attributes, x, y, z & w, but also support sequence access, making them work where a list or tuple is expected.

>>> v = [1, 2, 3, 4]
f = carb.Float4(v)
>>> f[0]
1.0
>>> f.y
2.0
>>> f[2]
3.0
>>> f.w
4.0

property w#

property x#

property y#

property z#

class carb.Framework#

breakpoint()#

get_plugins( self: carb._carb.Framework, ) → List[carb._carb.PluginDesc]#

load_plugins( self: carb._carb.Framework, loaded_file_wildcards: List[str] = [], search_paths: List[str] = [], ) → None#

start_plugin( self: carb._carb.Framework, plugin: str, ) → None#

startup( self: carb._carb.Framework, argv: List[str] = [], config: str = None, initial_plugins_search_paths: List[str] = [], config_format: str = 'toml', ) → None#

try_reload_plugins(self: carb._carb.Framework) → None#

unload_all_plugins(self: carb._carb.Framework) → None#

wait_for_native_debugger(timeout, stop, quiet)#

class carb.Int2#

property x#

property y#

class carb.Int3#

property x#

property y#

property z#

class carb.Int4#

property w#

property x#

property y#

property z#

class carb.InterfaceDesc#

property name#

property version#

class carb.PluginDesc#

property dependencies#

property impl#

property interfaces#

property libPath#

class carb.PluginHotReload#

Members:

DISABLED

ENABLED

DISABLED = <PluginHotReload.DISABLED: 0>#

ENABLED = <PluginHotReload.ENABLED: 1>#

property name#

property value#

class carb.PluginImplDesc#

property author#

property build#

property description#

property hotReload#

property name#

class carb.Subscription#

Subscription holder.

This object is returned by different subscription functions. Subscription lifetime is associated with this object. You can it while you need subscribed callback to be called. Then you can explicitly make it equal to None or call unsubscribe method or del it to unsubscribe.

Quite common patter of usage is when you have a class which subscribes to various callbacks and you want to subscription to stay valid while class instance is alive.

class Foo:
    def __init__(self):
        events = carb.events.get_events_interface()
        stream = events.create_event_stream()
        self._event_sub = stream.subscribe_to_pop(0, self._on_event)

    def _on_event(self, e):
        print(f'event {e}')

>>> f = Foo()
>>> # f receives some events
>>> f._event_sub = None
>>> f = None

unsubscribe(self: carb._carb.Subscription) → None#

class carb.Uint2#

property x#

property y#

class carb.Uint3#

property x#

property y#

property z#

class carb.Uint4#

property w#

property x#

property y#

property z#

class carb.Version#

property major#

property minor#

carb.answer_question(question: str) → str#

This function can answer some questions.

It currently only answers a limited set of questions so don’t expect it to know everything.

Parameters:: question – The question passed to the function, trailing question mark is not necessary and casing is not important.
Returns:: The answer to the question or empty string if it doesn’t know the answer.

carb.breakpoint() → None#

Issues a hardware breakpoint.

Warning: If a native debugger is not attached, this can cause an application error resulting in a crash.

Parameters:: None
Returns:: None

carb.get_framework() → carb::Framework#

carb.log( source: str, level: int, fileName: str, functionName: str, lineNumber: int, message: str, ) → None#

carb.log_error(msg)#

carb.log_info(msg)#

carb.log_verbose(msg)#

carb.log_warn(msg)#

carb.wait_for_native_debugger( timeout: float = -1.0, stop: bool = False, quiet: bool = False, ) → bool#

Waits for a debugger to attach.

Blocks (with GIL released) until a native debugger attaches to the process or a timeout occurs.

Parameters:

timeout – The time in seconds to wait. Negative values mean to wait forever. A value of 0 will check if a native debugger is attached without waiting. Optional, default value is -1.
stop – If True, a breakpoint is triggered immediately after a debugger attaches. If a timeout is reached instead, no breakpoint is triggered. Optional, default value is False.
quiet – When called if a debugger is not already attached a message is printed to stdout unless this is True. Optional, default value is False.

Returns:

True if a native debugger attached, False if a timeout is reached.

class carb.logging.ILogging#

add_logger( self: carb._carb.logging.ILogging, arg0: Callable[[str, int, str, int, str], None], ) → carb._carb.logging.LoggerHandle#

get_level_threshold(self: carb._carb.logging.ILogging) → int#

is_log_enabled(self: carb._carb.logging.ILogging) → bool#

remove_logger( self: carb._carb.logging.ILogging, arg0: carb._carb.logging.LoggerHandle, ) → None#

reset(self: carb._carb.logging.ILogging) → None#

set_level_threshold( self: carb._carb.logging.ILogging, arg0: int, ) → None#

set_level_threshold_for_source( self: carb._carb.logging.ILogging, arg0: str, arg1: carb._carb.logging.LogSettingBehavior, arg2: int, ) → None#

set_log_enabled( self: carb._carb.logging.ILogging, arg0: bool, ) → None#

set_log_enabled_for_source( self: carb._carb.logging.ILogging, arg0: str, arg1: carb._carb.logging.LogSettingBehavior, arg2: bool, ) → None#

class carb.logging.LogSettingBehavior#

Members:

INHERIT

OVERRIDE

INHERIT = <LogSettingBehavior.INHERIT: 0>#

OVERRIDE = <LogSettingBehavior.OVERRIDE: 1>#

property name#

property value#

class carb.logging.Logger#

class carb.logging.LoggerHandle#

carb.logging.acquire_logging( plugin_name: str = None, library_path: str = None, ) → carb._carb.logging.ILogging#

class carb.filesystem.DirectoryItemType#

Members:

FILE

carb.datasource#

class carb.datasource.ChangeAction#

ChangeAction.

Members:

CREATED

DELETED

MODIFIED

CONNECTION_LOST

CONNECTION_LOST = <ChangeAction.CONNECTION_LOST: 3>#

CREATED = <ChangeAction.CREATED: 0>#

DELETED = <ChangeAction.DELETED: 1>#

MODIFIED = <ChangeAction.MODIFIED: 2>#

property name#

property value#

class carb.datasource.Connection#

class carb.datasource.ConnectionDesc#

Descriptor for a connection.

property disable_cache#

property password#

property url#

property username#

class carb.datasource.ConnectionEventType#

Connection event results.

Members:

CONNECTED

DISCONNECTED

FAILED

INTERUPTED

CONNECTED = <ConnectionEventType.CONNECTED: 0>#

DISCONNECTED = <ConnectionEventType.DISCONNECTED: 2>#

FAILED = <ConnectionEventType.FAILED: 1>#

INTERUPTED = <ConnectionEventType.INTERUPTED: 3>#

property name#

property value#

class carb.datasource.IDataSource#

connect( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.ConnectionDesc, arg1: Callable[[carb.datasource._datasource.Connection, carb.datasource._datasource.ConnectionEventType], None], ) → None#

create_data( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: bytes, arg3: Callable[[carb.datasource._datasource.Response, str, str], None], ) → int#

delete_data( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: Callable[[carb.datasource._datasource.Response, str], None], ) → int#

disconnect( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, ) → None#

get_connection_id( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, ) → int#

get_connection_native_handle( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, ) → capsule#

get_connection_url( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, ) → str#

get_connection_username( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, ) → str#

get_supported_protocols( self: carb.datasource._datasource.IDataSource, ) → str#

is_writable( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: Callable[[carb.datasource._datasource.Response, str, bool], None], ) → int#

list_data( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: bool, arg3: Callable[[carb.datasource._datasource.Response, carb.datasource._datasource.ItemInfo], bool], arg4: Callable[[carb.datasource._datasource.Response, str], None], ) → int#

read_data( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: Callable[[carb.datasource._datasource.Response, str, bytes], None], ) → int#

read_data_sync( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, ) → bytes#

stop_request( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: int, ) → None#

subscribe_to_change_events( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: Callable[[str, carb.datasource._datasource.ChangeAction], None], ) → carb._carb.Subscription#

write_data( self: carb.datasource._datasource.IDataSource, arg0: carb.datasource._datasource.Connection, arg1: str, arg2: bytes, arg3: str, arg4: Callable[[carb.datasource._datasource.Response, str], None], ) → int#

class carb.datasource.ItemInfo#

Class holding the list data item information

property created_timestamp#

property hash#

property is_directory#

property is_writable#

property modified_timestamp#

property path#

property size#

property version#

class carb.datasource.Response#

Response results for data requests.

Members:

OK

ERROR_INVALID_PATH

ERROR_ALREADY_EXISTS

ERROR_INCOMPATIBLE_VERSION

ERROR_TIMEOUT

ERROR_ACCESS

ERROR_UNKNOWN

ERROR_ACCESS = <Response.ERROR_ACCESS: 5>#

ERROR_ALREADY_EXISTS = <Response.ERROR_ALREADY_EXISTS: 2>#

ERROR_INCOMPATIBLE_VERSION = <Response.ERROR_INCOMPATIBLE_VERSION: 3>#

ERROR_INVALID_PATH = <Response.ERROR_INVALID_PATH: 1>#

ERROR_TIMEOUT = <Response.ERROR_TIMEOUT: 4>#

ERROR_UNKNOWN = <Response.ERROR_UNKNOWN: 6>#

OK = <Response.OK: 0>#

property name#

property value#

carb.datasource.acquire_datasource_interface( plugin_name: str = None, library_path: str = None, ) → carb.datasource._datasource.IDataSource#

carb.datasource.get_datasource_interface( impl='carb.datasource-file.plugin', ) → IDataSource#: Returns cached carb.datasource.IDatasource interface

carb.dictionary#

class carb.dictionary.IDictionary#

create_item( self: carb.dictionary._dictionary.IDictionary, arg0: object, arg1: str, arg2: carb.dictionary._dictionary.ItemType, ) → carb.dictionary._dictionary.Item#

destroy_item( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → None#

get( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → object#

get_array_length( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → int#

get_as_bool( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → bool#

get_as_float( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → float#

get_as_int( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → int#

get_as_string( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → str#

get_dict_copy( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → object#

Creates python object from the supplied dictionary at path (supplied item is unchanged). Item is calculated via the path relative to the base item.

Parameters:

base_item – The base item.
path – Path, relative to the base item - to the item

Returns:

Python object with copies of the item data.

get_item( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → carb.dictionary._dictionary.Item#

get_item_child_by_index( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: int, ) → carb.dictionary._dictionary.Item#

get_item_child_by_index_mutable( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: int, ) → carb.dictionary._dictionary.Item#

get_item_child_count( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → int#

get_item_mutable( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → carb.dictionary._dictionary.Item#

get_item_name( self: carb.dictionary._dictionary.IDictionary, base_item: carb.dictionary._dictionary.Item, path: str = '', ) → str#

get_item_parent( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → carb.dictionary._dictionary.Item#

get_item_parent_mutable( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → carb.dictionary._dictionary.Item#

get_item_type( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → carb.dictionary._dictionary.ItemType#

get_preferred_array_type( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → carb.dictionary._dictionary.ItemType#

is_accessible_as( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.ItemType, arg1: carb.dictionary._dictionary.Item, ) → bool#

is_accessible_as_array_of( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.ItemType, arg1: carb.dictionary._dictionary.Item, ) → bool#

readLock( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → None#

set( self: carb.dictionary._dictionary.IDictionary, item: carb.dictionary._dictionary.Item, path: str = '', value: handle, ) → None#

set_bool( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: bool, ) → None#

set_bool_array( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: List[bool], ) → None#

set_float( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: float, ) → None#

set_float_array( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: List[float], ) → None#

set_int( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: int, ) → None#

set_int_array( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: List[int], ) → None#

set_string( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: str, ) → None#

set_string_array( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: List[str], ) → None#

unlock( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → None#

update( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, arg1: str, arg2: carb.dictionary._dictionary.Item, arg3: str, arg4: object, ) → None#

writeLock( self: carb.dictionary._dictionary.IDictionary, arg0: carb.dictionary._dictionary.Item, ) → None#

class carb.dictionary.ISerializer#

create_dictionary_from_file( self: carb.dictionary._dictionary.ISerializer, path: str, ) → carb.dictionary._dictionary.Item#

create_dictionary_from_string_buffer( self: carb.dictionary._dictionary.ISerializer, arg0: str, ) → carb.dictionary._dictionary.Item#

create_string_buffer_from_dictionary( self: carb.dictionary._dictionary.ISerializer, item: carb.dictionary._dictionary.Item, ser_options: int = 0, ) → str#

save_file_from_dictionary( self: carb.dictionary._dictionary.ISerializer, dict: carb.dictionary._dictionary.Item, path: str, options: int = 0, ) → None#

class carb.dictionary.Item#

clear(self: carb.dictionary._dictionary.Item) → None#

get( self: carb.dictionary._dictionary.Item, arg0: str, arg1: object, ) → object#

get_dict(self: carb.dictionary._dictionary.Item) → object#

get_key_at( self: carb.dictionary._dictionary.Item, arg0: int, ) → object#

get_keys(self: carb.dictionary._dictionary.Item) → List[str]#

class carb.dictionary.ItemType#

Members:

BOOL

INT

FLOAT

STRING

DICTIONARY

COUNT

BOOL = <ItemType.BOOL: 0>#

COUNT = <ItemType.COUNT: 5>#

DICTIONARY = <ItemType.DICTIONARY: 4>#

FLOAT = <ItemType.FLOAT: 2>#

INT = <ItemType.INT: 1>#

STRING = <ItemType.STRING: 3>#

property name#

property value#

class carb.dictionary.UpdateAction#

Members:

OVERWRITE

KEEP

KEEP = <UpdateAction.KEEP: 1>#

OVERWRITE = <UpdateAction.OVERWRITE: 0>#

property name#

property value#

carb.dictionary.acquire_dictionary_interface( plugin_name: str = None, library_path: str = None, ) → carb.dictionary._dictionary.IDictionary#

carb.dictionary.acquire_serializer_interface( plugin_name: str = None, library_path: str = None, ) → carb.dictionary._dictionary.ISerializer#

carb.dictionary.get_dictionary() → IDictionary#: Returns cached carb.dictionary.IDictionary interface (shorthand).

carb.dictionary.get_dictionary_interface() → IDictionary#: Returns cached carb.dictionary.IDictionary interface

carb.dictionary.get_json_serializer() → carb.dictionary._dictionary.ISerializer#

carb.dictionary.get_toml_serializer() → carb.dictionary._dictionary.ISerializer#

carb.dictionary.lru_cache(maxsize=128, typed=False)#

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

carb.eventdispatcher#

class carb.eventdispatcher.Event#

Event.

Contains the event_name and payload for a dispatched event.

property event_name#: The name of the event

get( self: carb.eventdispatcher._eventdispatcher.Event, key_name: str, ) → object#

Accesses a payload item by key name.

Parameters:: key_name – The name of a key to find in the payload.
Returns:: None if the key is not present, otherwise returns an object representative of the type in the payload.

has_key( self: carb.eventdispatcher._eventdispatcher.Event, key_name: str, ) → bool#

Returns True if a given key name is present in the payload.

Parameters:: key_name – The name of a key to check against the payload.
Returns:: True if the key is present in the payload; False otherwise.

class carb.eventdispatcher.IEventDispatcher#

dispatch_event( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, event_name: str, payload: handle = None, ) → int#

Dispatches an event and immediately calls all observers that would observe this particular event.

Finds and calls all observers (in the current thread) that observe the given event signature.

It is safe to recursively dispatch events (i.e. call dispatch_event() from within a called observer), but care must be taken to avoid endless recursion. See the rules in observe_event() for observers added during a dispatch_event() call.

Parameters:

event_name – (str) The name of the event to dispatch
payload – (dict) If present, must be a dict of key(str)/value(any) pairs.

Returns:

The number of observers that were called, excluding those from recursive calls.

has_observers( self: carb.eventdispatcher._eventdispatcher.IEventDispatcher, event_name: str, filter: handle = None, ) → bool#

Queries the Event Dispatcher whether any observers are listening to a specific event signature.

Emulates a call to dispatch_event() (without actually calling any observers) and returns True if any observers would be called.

Parameters:

event_name – (str) The event name to query
filter – [optional] (dict) If present, must be a dict of key(str)/value(any) pairs.

Returns:

True if at least one observer would be called with the given filter arguments; False otherwise.

observe_event(self: carb.eventdispatcher._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._eventdispatcher.ObserverGuard#

Registers an observer with the Event Dispatcher system.

An observer is a callback that is called whenever dispatch_event() is called. The observers are invoked in the thread that calls dispatch_event(), and multiple threads may be calling dispatch_event() simultaneously, so observers must be thread-safe unless the application can ensure synchronization around dispatch_event() calls.

Observers can pass an optional dictionary of filter arguments. The key/value pairs of filter arguments cause an observer to only be invoked for a dispatch_event() call that contains at least the same values. For instance, having a filter dictionary of {“WindowID”: 1234} will only cause the observer to be called if dispatch_event() is given the same value as a “WindowID” parameter.

Observers can be added inside of an observer notification (i.e. during a call to dispatch_event()), however these new observers will not be called for currently the dispatching event. A subsequent recursive call to dispatch_event() (on the current thread only) will also call the new observer. The new observer will be available to all other threads once the dispatch_event() call (in which it was added) completes.

Parameters:

order – (int) A value determining call order. Observers with lower order values are called earlier. Observers with the same order value and same filter argument values will be called in the order they are registered. Observers with the same order value with different filter arguments are called in an indeterminate order.
event_name – (str) The event name to observe
on_event – (function) A function that is invoked when an event matching event_name and any filter arguments is dispatched.
filter – [optional] (dict) If present, must be a dict of key(str)/value(any) pairs.
observer_name – [optional] (str) If present, the name of the observer for debugging and profiling. If omitted, “<python>” is used instead.

Returns:

An ObserverGuard object that, when collected, removes the observer from the Event Dispatcher system.

class carb.eventdispatcher.IMessageQueue#

An instance of a message queue.

A message queue is a one-way weak coupling device that allows “messages” to be sent from a variety of senders and received by a specific target. A message queue has a push-side and a pop-side. The push-side can be accessed by any thread. The pop-side can only be accessed by the owning thread, or a group of threads if no owning thread is specified. Violations of this policy are enforced by raising errors.

Can be created with IMessageQueueFactory.create_message_queue(), or an existing message queue can be found with IMessageQueueFactory.get_message_queue().

get_name( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, ) → str#

Retrieves the unique name of this message queue.

Parameters:: None
Returns:: The unique name of this message queue.
Return type:: str

get_owning_thread( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, ) → int#

Retrieves the thread ID of the thread which owns this message queue.

This value should be comparable with threading.get_ident().

Parameters:: None
Returns:: The thread identifier that owns the queue, or 0 if no single thread owns the queue.
Return type:: uint

has_messages( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, ) → bool#

Returns whether this message queue has pending messages.

Parameters:: None
Returns:: True if there are messages in the queue; False if there are no messages in the queue.
Return type:: bool

peek( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, fn: Callable[[carb.eventdispatcher._eventdispatcher.Event], None], ) → bool#

Inspects the message at the front of the queue, if any, without removing it.

The message is not removed when this function is called. Call pop() to process and remove the message.

This function only works in a single-owner-thread situation, otherwise a RuntimeError is raised.

Parameters:

fn – (function) A function that is called with a carb.eventdispatcher.Event as the only parameter.

Returns:

True if the given function was called with a message; False if there are no messages in the queue.

Return type:

bool

Raises:

IndexError – The message queue has been stopped.
RuntimeError – The calling thread is not the owner thread, the queue is not in single-thread mode, or another error.

async pop(fn)#

Waits until a message has been pushed to the queue and might be available. Returns after the message is handled.

Note, this function must be awaited. The message is removed from the queue atomically before processing. In a single-owner-thread situation this function must be called within the context of the owning thread.

If a task or thread is waiting on the message, the message will be considered ‘completed’ and unblock the waiting task/thread as soon as fn() returns, even if the carb.eventdispatcher.Event passed to the function is retained.

This function returns once a message is processed. If the queue is stopped with stop() while awaiting, this function will stop waiting and will throw IndexError.

Parameters:

fn – (function) A function that is called with a carb.eventdispatcher.Event as the only parameter.

Returns:

None

Raises:

IndexError – The message queue has been stopped.
RuntimeError – The calling thread is not the owner thread, or another error.

push(event_name, payload: dict | None = None)#

Posts a message to the message queue without waiting for the message to be processed.

Parameters:

event_name – (str) The event name for the message.
payload – (dict) (optional) A dictionary that functions as the payload for the message.

Returns:

None

Raises:

IndexError – The message queue has been stopped.
MemoryError – Failed to allocate memory for the message.
RuntimeError – Any other error.)

async push_and_wait(event_name, payload: dict | None = None)#

Pushes a message to the message queue and does not return until the message is processed.

Note, this function must be awaited. For a function that pushes a message without waiting, use push().

Parameters:

event_name – (str) The event name for the message
payload – (dict) (optional) A dictionary that functions as the payload for the message.

Returns:

None

Raises:

IndexError – The message queue has been stopped.
MemoryError – Failed to allocate memory for the message.
RuntimeError – Any other error.

stop( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, ) → None#

Stops the message queue before destruction. This is a one-time, irreversible command to a message queue that the queue is no longer processing messages. It is not required to call this function before the last reference is removed and *this is destroyed.

When stop() returns it is guaranteed that:

Any future attempts to push messages or pop messages will result in an IndexError being raised.
All threads or tasks that are awaiting a message or waiting for a message to be processed have been unblocked. The existing function calls and future function calls will raise an IndexError.
The message queue is removed from IMessageQueueFactory; attempts to retrieve the message queue by name will return None and a new message queue with the same name can be created again.

Subsequent calls to this function will raise IndexError as the message queue has already been stopped.

It is undefined behavior to call this from within the functions passed to pop() or peek(). Instead, it is recommended that the handlers for pop() or peek() set a flag that can be checked after the pop() or peek() returns which then calls stop().

Parameters:

None

Returns:

None

Raises:

IndexError – The message queue has already been stopped.
RuntimeError – The calling thread does not have permission to stop the queue, or another error.

try_pop( self: carb.eventdispatcher._eventdispatcher.IMessageQueue, fn: Callable[[carb.eventdispatcher._eventdispatcher.Event], None], ) → bool#

Pops the message at the front of the queue and calls a function with the message.

The message is removed from the queue atomically before processing. In a single-owner-thread situation, this function must be called within the context of the owning thread.

If a task or thread is waiting on the message, the message will be considered ‘completed’ and unblock the waiting task/thread as soon as fn() returns, even if the carb.eventdispatcher.Event passed to the function is retained.

Parameters:

fn – (function) A function that is called with a carb.eventdispatcher.Event as the only parameter.

Returns:

True if the given function was called with a message; False if there are no messages in the queue.

Return type:

bool

Raises:

IndexError – The message queue has been stopped.
RuntimeError – The calling thread is not the owner thread, or another error.

class carb.eventdispatcher.IMessageQueueFactory#

create_message_queue(

self: carb.eventdispatcher._eventdispatcher.IMessageQueueFactory,

name: str,

**kwargs,

) → Tuple[carb.eventdispatcher._eventdispatcher.IMessageQueue, bool]#

Creates a message queue with the given name and parameters, or returns an existing message queue with the given name.

Parameters:

name – (str) The unique name of the message queue. If the name already exists, the message queue will not be created but the previously-created message queue will be returned (params will be ignored). Since names must be unique, a scheme such as reverse-DNS is recommended.

Keyword Arguments:

owning_thread – (int, default: 0) The thread that owns the message queue. If zero, the message queue can be popped by multiple threads. If a specific thread owns the message queue then an error will occur if any other thread attempts to pop the message queue, and the message queue will be optimized for the owning thread. Message queues that are created from a task (carb::tasking::ITasking) or thread pool should use zero here instead of using the calling thread. NOTE: This value should be via threading.get_native_id(), NOT threading.get_ident().

Returns:

Tuple of (IMessageQueue, bool) where the IMessageQueue is the message queue and the bool is whether it was created by this call (True), or an existing message queue was found and returned (False).

Raises:

MemoryError – failed to allocate the message queue
RuntimeError – an invalid argument was passed

get_message_queue( self: carb.eventdispatcher._eventdispatcher.IMessageQueueFactory, name: str, ) → carb.eventdispatcher._eventdispatcher.IMessageQueue#

Retrieves a message queue with the given name.

Parameters:: name – (str) The unique name of a previously-created message queue.
Returns:: A message queue found by name.

class carb.eventdispatcher.ObserverGuard#

ObserverGuard.

Lifetime control for a registered observer. Unregister the observer by calling the reset() function or allowing the object to be collected.

property enabled#: Sets or gets the enabled state of an observer.

property name#

gets the name of the observer.

Type:: Read-only

property order#: Sets or gets the integer order of the observer.

reset( self: carb.eventdispatcher._eventdispatcher.ObserverGuard, ) → None#

Explicitly stops an observer.

Having this object collected has the same effect, implicitly.

This is safe to perform while dispatching.

Since observers can be in use by this thread or any thread, this function is carefully synchronized with all other Event Dispatcher operations.

During reset(), further calls to the observer are prevented, even if other threads are currently dispatching an event that would be observed by the observer in question.
If any other thread is currently calling the observer in question, reset() will wait until all other threads have left the observer callback function.
If the observer function is not in the backtrace of the current thread, the observer function is immediately released.
If the observer function is in the backtrace of the current thread, reset() will return without waiting and without releasing the observer callback. Instead, releasing the function will be performed when the dispatch_event() call in the current thread finishes.

When reset() returns, it is guaranteed that the observer callback function will no longer be called and all calls to it have completed (except if the calling thread is dispatching).

carb.eventdispatcher.acquire_eventdispatcher_interface() → carb::eventdispatcher::IEventDispatcher#: Acquires the Event Dispatcher interface.

carb.eventdispatcher.acquire_messagequeue_factory_interface() → carb::eventdispatcher::IMessageQueueFactory#: Acquires the IMessageQueueFactory interface.

carb.eventdispatcher.get_eventdispatcher() → IEventDispatcher#: Returns cached carb.eventdispatcher.IEventDispatcher interface (shorthand).

carb.eventdispatcher.get_eventdispatcher_interface() → IEventDispatcher#: Returns cached carb.eventdispatcher.IEventDispatcher interface

carb.eventdispatcher.get_messagequeue_factory() → IMessageQueueFactory#: Returns cached carb.eventdispatcher.IMessageQueueFactory interface (shorthand)

carb.eventdispatcher.get_messagequeue_factory_interface() → IMessageQueueFactory#: Returns cached carb.eventdispatcher.IMessageQueueFactory interface

carb.eventdispatcher.lru_cache(maxsize=128, typed=False)#

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

carb.events#

class carb.events.AdapterType#

Members:

DISPATCH

PUSH_PUMP

FULL

DISPATCH = <AdapterType.DISPATCH: 0>#

FULL = <AdapterType.FULL: 2>#

PUSH_PUMP = <AdapterType.PUSH_PUMP: 1>#

property name#

property value#

class carb.events.IEvent#

Event.

Event has an Event type, a sender id and a payload. Payload is a dictionary like item with arbitrary data.

consume(self: carb.events._events.IEvent) → None#: Consume event to stop it propagating to other listeners down the line.

property payload#

property sender#

property type#

class carb.events.IEventStream#

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

Subscribes to event dispatching on the stream.

See Subscription for more information on subscribing mechanism.

Parameters:

fn – The callback to be called on event dispatch.
order – An integer order specifier. Lower numbers are called first. Negative numbers are allowed. Default is 0.
name – The name of the subscription for profiling. If no name is provided one is generated from the traceback of the calling function.

Returns:

The subscription holder.

create_subscription_to_pop_by_type( self: carb.events._events.IEventStream, event_type: int, fn: Callable[[carb.events._events.IEvent], None], order: int = 0, name: str = None, ) → carb.events._events.ISubscription#

Subscribes to event dispatching on the stream.

See Subscription for more information on subscribing mechanism.

Parameters:

event_type – Event type to listen to.
fn – The callback to be called on event dispatch.
order – An integer order specifier. Lower numbers are called first. Negative numbers are allowed. Default is 0.
name – The name of the subscription for profiling. If no name is provided one is generated from the traceback of the calling function.

Returns:

The subscription holder.

create_subscription_to_push( self: carb.events._events.IEventStream, fn: Callable[[carb.events._events.IEvent], None], order: int = 0, name: str = None, ) → carb.events._events.ISubscription#

Subscribes to pushing events into stream.

See Subscription for more information on subscribing mechanism.

Parameters:

fn – The callback to be called on event push.
order – An integer order specifier. Lower numbers are called first. Negative numbers are allowed. Default is 0.
name – The name of the subscription for profiling. If no name is provided one is generated from the traceback of the calling function.

Returns:

The subscription holder.

create_subscription_to_push_by_type( self: carb.events._events.IEventStream, event_type: int, fn: Callable[[carb.events._events.IEvent], None], order: int = 0, name: str = None, ) → carb.events._events.ISubscription#

Subscribes to pushing events into stream.

See Subscription for more information on subscribing mechanism.

Parameters:

event_type – Event type to listen to.
fn – The callback to be called on event push.
order – An integer order specifier. Lower numbers are called first. Negative numbers are allowed. Default is 0.
name – The name of the subscription for profiling. If no name is provided one is generated from the traceback of the calling function.

Returns:

The subscription holder.

dispatch( self: carb.events._events.IEventStream, event_type: int = 0, sender: int = 0, payload: dict = {}, ) → None#

Dispatch Event immediately without putting it into stream.

Parameters:

event_type (int) – Event type.
sender (int) – Sender id. Unique can be acquired using acquire_unique_sender_id().
dict (Dict) – Event payload.

property event_count#

get_subscription_to_pop_order( self: carb.events._events.IEventStream, name: str, ) → object#

get_subscription_to_push_order( self: carb.events._events.IEventStream, name: str, ) → object#

get_subscriptions_to_pop( self: carb.events._events.IEventStream, ) → tuple#: Get subscriptions to pop. Return tuple with all subscriptions.

get_subscriptions_to_push( self: carb.events._events.IEventStream, ) → tuple#: Get subscriptions to push. Return tuple with all subscriptions.

property name#

Gets the name of the EventStream.

Returns:: The name of the event stream.

async next_event(order: int = 0, name: str = '')#: Async wait for next event.

async next_event_by_type( event_type: int, order: int = 0, name: str = '', )#: Async wait for next event of particular type.

pop( self: carb.events._events.IEventStream, ) → carb.events._events.IEvent#

Pop event.

This function blocks execution until there is an event to pop.

Returns:: (Event) object. You own this object, it can be stored.

pump(self: carb.events._events.IEventStream) → None#

Pump event stream.

Dispatches all events in a stream.

push( self: carb.events._events.IEventStream, event_type: int = 0, sender: int = 0, payload: dict = {}, ) → None#

Push Event into stream.

Parameters:

event_type (int) – Event type.
sender (int) – Sender id. Unique can be acquired using acquire_unique_sender_id().
dict (Dict) – Event payload.

set_subscription_to_pop_order( self: carb.events._events.IEventStream, name: str, order: int, ) → bool#: Set subscription to pop order by name of subscription.

set_subscription_to_push_order( self: carb.events._events.IEventStream, name: str, order: int, ) → bool#: Set subscription to push order by name of subscription.

try_pop( self: carb.events._events.IEventStream, ) → carb.events._events.IEvent#

Try pop event.

Returns:: Pops (Event) if stream is not empty or return None.

class carb.events.IEvents#

acquire_unique_sender_id( self: carb.events._events.IEvents, ) → int#

Acquire unique sender id.

Call release_unique_sender_id() when it is not needed anymore. It can be reused then.

create_event_stream( self: carb.events._events.IEvents, name: str = None, ) → carb.events._events.IEventStream#

Create new .EventStream.

Parameters:: name – The name of the .EventStream for profiling. If no name is provided one is generated from the traceback of the calling function.

release_unique_sender_id( self: carb.events._events.IEvents, arg0: int, ) → None#

class carb.events.IEventsAdapter#

create_adapter(

self: carb.events._events.IEventsAdapter,

type: carb.events._events.AdapterType,

name: str,

mappings: sequence,

**kwargs,

) → carb.events._events.IEventStream#

class carb.events.ISubscription#

Subscription holder.

property enabled#: Enable status of this subscription.

property name#

Returns the name of this subscription.

Returns:: The name of this subscription.

property order#: Order of this subscription.

unsubscribe( self: carb.events._events.ISubscription, ) → None#: Unsubscribes this subscription.

class carb.events.MappingEntry#

property dispatch_name#

property push_name#

property type#

carb.events.acquire_events_adapter_interface() → carb::events::IEventsAdapter#

carb.events.acquire_events_interface() → carb::events::IEvents#

carb.events.get_events_adapter_interface() → IEvents#: Returns cached carb.events.IEvents interface

carb.events.get_events_interface() → IEvents#: Returns cached carb.events.IEvents interface

carb.events.type_from_string(arg0: str) → int#

carb.input#

pybind11 carb.input bindings

class carb.input.ActionEvent#

property action#

property flags#

property value#

class carb.input.ActionMappingDesc#

property device#

property deviceType#

property input#

property modifiers#

class carb.input.ActionMappingSet#

class carb.input.DeviceType#

Members:

KEYBOARD

MOUSE

GAMEPAD

GAMEPAD = <DeviceType.GAMEPAD: 2>#

KEYBOARD = <DeviceType.KEYBOARD: 0>#

MOUSE = <DeviceType.MOUSE: 1>#

property name#

property value#

class carb.input.EventType#

Members:

UNKNOWN

UNKNOWN = <EventType.UNKNOWN: 0>#

property name#

property value#

class carb.input.FilterResult#

Members:

RETAIN

CONSUME

CONSUME = <FilterResult.CONSUME: 1>#

RETAIN = <FilterResult.RETAIN: 0>#

property name#

property value#

class carb.input.Gamepad#

class carb.input.GamepadConnectionEvent#

property device#

property gamepad#

property type#

class carb.input.GamepadConnectionEventType#

Members:

CREATED

CONNECTED

DISCONNECTED

DESTROYED

CONNECTED = <GamepadConnectionEventType.CONNECTED: 1>#

CREATED = <GamepadConnectionEventType.CREATED: 0>#

DESTROYED = <GamepadConnectionEventType.DESTROYED: 3>#

DISCONNECTED = <GamepadConnectionEventType.DISCONNECTED: 2>#

property name#

property value#

class carb.input.GamepadEvent#

property device#

property gamepad#

property input#

property value#

class carb.input.GamepadInput#

Members:

LEFT_STICK_RIGHT

LEFT_STICK_LEFT

LEFT_STICK_UP

LEFT_STICK_DOWN

RIGHT_STICK_RIGHT

RIGHT_STICK_LEFT

RIGHT_STICK_UP

RIGHT_STICK_DOWN

LEFT_TRIGGER

RIGHT_TRIGGER

A

B

X

Y

LEFT_SHOULDER

RIGHT_SHOULDER

MENU1

MENU2

LEFT_STICK

RIGHT_STICK

DPAD_UP

DPAD_RIGHT

DPAD_DOWN

DPAD_LEFT

COUNT

A = <GamepadInput.A: 10>#

B = <GamepadInput.B: 11>#

COUNT = <GamepadInput.COUNT: 24>#

DPAD_DOWN = <GamepadInput.DPAD_DOWN: 22>#

DPAD_LEFT = <GamepadInput.DPAD_LEFT: 23>#

DPAD_RIGHT = <GamepadInput.DPAD_RIGHT: 21>#

DPAD_UP = <GamepadInput.DPAD_UP: 20>#

LEFT_SHOULDER = <GamepadInput.LEFT_SHOULDER: 14>#

LEFT_STICK = <GamepadInput.LEFT_STICK: 18>#

LEFT_STICK_DOWN = <GamepadInput.LEFT_STICK_DOWN: 3>#

LEFT_STICK_LEFT = <GamepadInput.LEFT_STICK_LEFT: 1>#

LEFT_STICK_RIGHT = <GamepadInput.LEFT_STICK_RIGHT: 0>#

LEFT_STICK_UP = <GamepadInput.LEFT_STICK_UP: 2>#

LEFT_TRIGGER = <GamepadInput.LEFT_TRIGGER: 8>#

MENU1 = <GamepadInput.MENU1: 16>#

MENU2 = <GamepadInput.MENU2: 17>#

RIGHT_SHOULDER = <GamepadInput.RIGHT_SHOULDER: 15>#

RIGHT_STICK = <GamepadInput.RIGHT_STICK: 19>#

RIGHT_STICK_DOWN = <GamepadInput.RIGHT_STICK_DOWN: 7>#

RIGHT_STICK_LEFT = <GamepadInput.RIGHT_STICK_LEFT: 5>#

RIGHT_STICK_RIGHT = <GamepadInput.RIGHT_STICK_RIGHT: 4>#

RIGHT_STICK_UP = <GamepadInput.RIGHT_STICK_UP: 6>#

RIGHT_TRIGGER = <GamepadInput.RIGHT_TRIGGER: 9>#

X = <GamepadInput.X: 12>#

Y = <GamepadInput.Y: 13>#

property name#

property value#

class carb.input.IInput#

add_action_mapping(*args, **kwargs)#

Overloaded function.

add_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, keyboard: carb.input.Keyboard, keyboard_input: carb.input.KeyboardInput, modifiers: int = 0) -> int
add_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, mouse: carb.input.Mouse, mouse_input: carb.input.MouseInput, modifiers: int = 0) -> int
add_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, gamepad: carb.input.Gamepad, gamepad_input: carb.input.GamepadInput) -> int

clear_action_mappings( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, ) → None#

create_action_mapping_set( self: carb.input.IInput, arg0: str, ) → carb.input.ActionMappingSet#

destroy_action_mapping_set( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, ) → None#

distribute_buffered_events(self: carb.input.IInput) → None#

filter_buffered_events( self: carb.input.IInput, arg0: Callable[[carb.input.InputEvent], carb.input.FilterResult], ) → None#

get_action_button_flags(*args, **kwargs)#

Overloaded function.

get_action_button_flags(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str) -> int
get_action_button_flags(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str) -> int

get_action_count( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, ) → int#

get_action_mapping_count( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, ) → int#

get_action_mapping_set_by_path(*args, **kwargs)#

Overloaded function.

get_action_mapping_set_by_path(self: carb.input.IInput, arg0: str) -> carb.input.ActionMappingSet
get_action_mapping_set_by_path(self: carb.input.IInput, arg0: str) -> carb.input.ActionMappingSet

get_action_mappings( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, ) → List[carb.input.ActionMappingDesc]#

get_action_value(*args, **kwargs)#

Overloaded function.

get_action_value(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str) -> float
get_action_value(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str) -> float

get_actions( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, ) → List[str]#

get_device_name( self: carb.input.IInput, arg0: carb.input.InputDevice, ) → str#

get_device_type( self: carb.input.IInput, arg0: carb.input.InputDevice, ) → carb.input.DeviceType#

get_gamepad_button_flags( self: carb.input.IInput, arg0: carb.input.Gamepad, arg1: carb.input.GamepadInput, ) → int#

get_gamepad_guid( self: carb.input.IInput, arg0: carb.input.Gamepad, ) → str#

get_gamepad_name( self: carb.input.IInput, arg0: carb.input.Gamepad, ) → str#

get_gamepad_value( self: carb.input.IInput, arg0: carb.input.Gamepad, arg1: carb.input.GamepadInput, ) → float#

get_global_modifier_flags( self: carb.input.IInput, modifiers: int = 0, mouse_buttons: object = None, ) → int#

get_input_provider( self: carb.input.IInput, ) → carb::input::InputProvider#

get_keyboard_button_flags( self: carb.input.IInput, arg0: carb.input.Keyboard, arg1: carb.input.KeyboardInput, ) → int#

get_keyboard_name( self: carb.input.IInput, arg0: carb.input.Keyboard, ) → str#

get_keyboard_value( self: carb.input.IInput, arg0: carb.input.Keyboard, arg1: carb.input.KeyboardInput, ) → float#

get_modifier_flags( self: carb.input.IInput, modifiers: int = 0, input_devices: List[carb.input.InputDevice] = [], device_types: List[carb.input.DeviceType] = [], mouse_buttons: object = None, ) → int#

get_mouse_button_flags( self: carb.input.IInput, arg0: carb.input.Mouse, arg1: carb.input.MouseInput, ) → int#

get_mouse_coords_normalized( self: carb.input.IInput, arg0: carb.input.Mouse, ) → carb._carb.Float2#

get_mouse_coords_pixel( self: carb.input.IInput, arg0: carb.input.Mouse, ) → carb._carb.Float2#

get_mouse_name( self: carb.input.IInput, arg0: carb.input.Mouse, ) → str#

get_mouse_value( self: carb.input.IInput, arg0: carb.input.Mouse, arg1: carb.input.MouseInput, ) → float#

remove_action_mapping( self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: int, ) → None#

set_action_mapping(*args, **kwargs)#

Overloaded function.

set_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, index: int, keyboard: carb.input.Keyboard, keyboard_input: carb.input.KeyboardInput, modifiers: int = 0) -> None
set_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, index: int, mouse: carb.input.Mouse, mouse_input: carb.input.MouseInput, modifiers: int = 0) -> None
set_action_mapping(self: carb.input.IInput, action_mapping_set: carb.input.ActionMappingSet, action: str, index: int, gamepad: carb.input.Gamepad, gamepad_input: carb.input.GamepadInput) -> None

set_default_action_mapping(*args, **kwargs)#

Overloaded function.

set_default_action_mapping(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: carb.input.Keyboard, arg3: carb.input.KeyboardInput, arg4: int) -> bool
set_default_action_mapping(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: carb.input.Gamepad, arg3: carb.input.GamepadInput) -> bool
set_default_action_mapping(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: carb.input.Mouse, arg3: carb.input.MouseInput, arg4: int) -> bool

shutdown(self: carb.input.IInput) → None#

startup(self: carb.input.IInput) → None#

subscribe_to_action_events(*args, **kwargs)#

Overloaded function.

subscribe_to_action_events(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: Callable[[carb.input.ActionEvent], bool]) -> int
subscribe_to_action_events(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: Callable[[carb.input.ActionEvent], bool]) -> int

subscribe_to_gamepad_connection_events( self: carb.input.IInput, arg0: Callable[[carb.input.GamepadConnectionEvent], None], ) → int#

subscribe_to_gamepad_events( self: carb.input.IInput, arg0: carb.input.Gamepad, arg1: Callable[[carb.input.GamepadEvent], bool], ) → int#

subscribe_to_input_events( self: carb.input.IInput, eventFn: Callable[[carb.input.InputEvent], bool], eventTypes: int = 4294967295, device: carb.input.InputDevice = None, order: int = -1, ) → int#

subscribe_to_keyboard_events( self: carb.input.IInput, arg0: carb.input.Keyboard, arg1: Callable[[carb.input.KeyboardEvent], bool], ) → int#

subscribe_to_mouse_events( self: carb.input.IInput, arg0: carb.input.Mouse, arg1: Callable[[carb.input.MouseEvent], bool], ) → int#

unsubscribe_to_action_events(*args, **kwargs)#

Overloaded function.

unsubscribe_to_action_events(self: carb.input.IInput, arg0: int) -> None
unsubscribe_to_action_events(self: carb.input.IInput, arg0: int) -> None

unsubscribe_to_gamepad_connection_events( self: carb.input.IInput, arg0: int, ) → None#

unsubscribe_to_gamepad_events( self: carb.input.IInput, arg0: carb.input.Gamepad, arg1: int, ) → None#

unsubscribe_to_input_events( self: carb.input.IInput, arg0: int, ) → None#

unsubscribe_to_keyboard_events( self: carb.input.IInput, arg0: carb.input.Keyboard, arg1: int, ) → None#

unsubscribe_to_mouse_events( self: carb.input.IInput, arg0: carb.input.Mouse, arg1: int, ) → None#

class carb.input.InputDevice#

class carb.input.InputEvent#

property device#

property deviceType#

property event#

class carb.input.InputProvider#

buffer_gamepad_event( self: carb.input.InputProvider, arg0: carb.input.Gamepad, arg1: carb.input.GamepadInput, arg2: float, ) → None#

buffer_keyboard_char_event( self: carb.input.InputProvider, arg0: carb.input.Keyboard, arg1: str, arg2: int, ) → None#

buffer_keyboard_key_event( self: carb.input.InputProvider, arg0: carb.input.Keyboard, arg1: carb.input.KeyboardEventType, arg2: carb.input.KeyboardInput, arg3: int, ) → None#

buffer_mouse_event( self: carb.input.InputProvider, arg0: carb.input.Mouse, arg1: carb.input.MouseEventType, arg2: carb._carb.Float2, arg3: int, arg4: carb._carb.Float2, ) → None#

create_gamepad( self: carb.input.InputProvider, arg0: str, arg1: str, ) → carb.input.Gamepad#

create_keyboard( self: carb.input.InputProvider, arg0: str, ) → carb.input.Keyboard#

create_mouse( self: carb.input.InputProvider, arg0: str, ) → carb.input.Mouse#

destroy_gamepad( self: carb.input.InputProvider, arg0: carb.input.Gamepad, ) → None#

destroy_keyboard( self: carb.input.InputProvider, arg0: carb.input.Keyboard, ) → None#

destroy_mouse( self: carb.input.InputProvider, arg0: carb.input.Mouse, ) → None#

set_gamepad_connected( self: carb.input.InputProvider, arg0: carb.input.Gamepad, arg1: bool, ) → None#

update_gamepad( self: carb.input.InputProvider, arg0: carb.input.Gamepad, ) → None#

update_keyboard( self: carb.input.InputProvider, arg0: carb.input.Keyboard, ) → None#

update_mouse( self: carb.input.InputProvider, arg0: carb.input.Mouse, ) → None#

class carb.input.Keyboard#

class carb.input.KeyboardEvent#

property device#

property input#

property keyboard#

property modifiers#

property type#

class carb.input.KeyboardEventType#

Members:

KEY_PRESS

KEY_REPEAT

KEY_RELEASE

CHAR

CHAR = <KeyboardEventType.CHAR: 3>#

KEY_PRESS = <KeyboardEventType.KEY_PRESS: 0>#

KEY_RELEASE = <KeyboardEventType.KEY_RELEASE: 2>#

KEY_REPEAT = <KeyboardEventType.KEY_REPEAT: 1>#

property name#

property value#

class carb.input.KeyboardInput#

Members:

UNKNOWN

SPACE

APOSTROPHE

COMMA

MINUS

PERIOD

SLASH

KEY_0

KEY_1

KEY_2

KEY_3

KEY_4

KEY_5

KEY_6

KEY_7

KEY_8

KEY_9

SEMICOLON

EQUAL

A

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z

LEFT_BRACKET

BACKSLASH

RIGHT_BRACKET

GRAVE_ACCENT

ESCAPE

TAB

ENTER

BACKSPACE

INSERT

DEL

RIGHT

LEFT

DOWN

UP

PAGE_UP

PAGE_DOWN

HOME

END

CAPS_LOCK

SCROLL_LOCK

NUM_LOCK

PRINT_SCREEN

PAUSE

F1

F2

F3

F4

F5

F6

F7

F8

F9

F10

F11

F12

NUMPAD_0

NUMPAD_1

NUMPAD_2

NUMPAD_3

NUMPAD_4

NUMPAD_5

NUMPAD_6

NUMPAD_7

NUMPAD_8

NUMPAD_9

NUMPAD_DEL

NUMPAD_DIVIDE

NUMPAD_MULTIPLY

NUMPAD_SUBTRACT

NUMPAD_ADD

NUMPAD_ENTER

NUMPAD_EQUAL

LEFT_SHIFT

LEFT_CONTROL

LEFT_ALT

LEFT_SUPER

RIGHT_SHIFT

RIGHT_CONTROL

RIGHT_ALT

RIGHT_SUPER

MENU

COUNT

A = <KeyboardInput.A: 19>#

APOSTROPHE = <KeyboardInput.APOSTROPHE: 2>#

B = <KeyboardInput.B: 20>#

BACKSLASH = <KeyboardInput.BACKSLASH: 46>#

BACKSPACE = <KeyboardInput.BACKSPACE: 52>#

C = <KeyboardInput.C: 21>#

CAPS_LOCK = <KeyboardInput.CAPS_LOCK: 63>#

COMMA = <KeyboardInput.COMMA: 3>#

COUNT = <KeyboardInput.COUNT: 106>#

D = <KeyboardInput.D: 22>#

DEL = <KeyboardInput.DEL: 54>#

DOWN = <KeyboardInput.DOWN: 57>#

E = <KeyboardInput.E: 23>#

END = <KeyboardInput.END: 62>#

ENTER = <KeyboardInput.ENTER: 51>#

EQUAL = <KeyboardInput.EQUAL: 18>#

ESCAPE = <KeyboardInput.ESCAPE: 49>#

F = <KeyboardInput.F: 24>#

F1 = <KeyboardInput.F1: 68>#

F10 = <KeyboardInput.F10: 77>#

F11 = <KeyboardInput.F11: 78>#

F12 = <KeyboardInput.F12: 79>#

F2 = <KeyboardInput.F2: 69>#

F3 = <KeyboardInput.F3: 70>#

F4 = <KeyboardInput.F4: 71>#

F5 = <KeyboardInput.F5: 72>#

F6 = <KeyboardInput.F6: 73>#

F7 = <KeyboardInput.F7: 74>#

F8 = <KeyboardInput.F8: 75>#

F9 = <KeyboardInput.F9: 76>#

G = <KeyboardInput.G: 25>#

GRAVE_ACCENT = <KeyboardInput.GRAVE_ACCENT: 48>#

H = <KeyboardInput.H: 26>#

HOME = <KeyboardInput.HOME: 61>#

I = <KeyboardInput.I: 27>#

INSERT = <KeyboardInput.INSERT: 53>#

J = <KeyboardInput.J: 28>#

K = <KeyboardInput.K: 29>#

KEY_0 = <KeyboardInput.KEY_0: 7>#

KEY_1 = <KeyboardInput.KEY_1: 8>#

KEY_2 = <KeyboardInput.KEY_2: 9>#

KEY_3 = <KeyboardInput.KEY_3: 10>#

KEY_4 = <KeyboardInput.KEY_4: 11>#

KEY_5 = <KeyboardInput.KEY_5: 12>#

KEY_6 = <KeyboardInput.KEY_6: 13>#

KEY_7 = <KeyboardInput.KEY_7: 14>#

KEY_8 = <KeyboardInput.KEY_8: 15>#

KEY_9 = <KeyboardInput.KEY_9: 16>#

L = <KeyboardInput.L: 30>#

LEFT = <KeyboardInput.LEFT: 56>#

LEFT_ALT = <KeyboardInput.LEFT_ALT: 99>#

LEFT_BRACKET = <KeyboardInput.LEFT_BRACKET: 45>#

LEFT_CONTROL = <KeyboardInput.LEFT_CONTROL: 98>#

LEFT_SHIFT = <KeyboardInput.LEFT_SHIFT: 97>#

LEFT_SUPER = <KeyboardInput.LEFT_SUPER: 100>#

M = <KeyboardInput.M: 31>#

MENU = <KeyboardInput.MENU: 105>#

MINUS = <KeyboardInput.MINUS: 4>#

N = <KeyboardInput.N: 32>#

NUMPAD_0 = <KeyboardInput.NUMPAD_0: 80>#

NUMPAD_1 = <KeyboardInput.NUMPAD_1: 81>#

NUMPAD_2 = <KeyboardInput.NUMPAD_2: 82>#

NUMPAD_3 = <KeyboardInput.NUMPAD_3: 83>#

NUMPAD_4 = <KeyboardInput.NUMPAD_4: 84>#

NUMPAD_5 = <KeyboardInput.NUMPAD_5: 85>#

NUMPAD_6 = <KeyboardInput.NUMPAD_6: 86>#

NUMPAD_7 = <KeyboardInput.NUMPAD_7: 87>#

NUMPAD_8 = <KeyboardInput.NUMPAD_8: 88>#

NUMPAD_9 = <KeyboardInput.NUMPAD_9: 89>#

NUMPAD_ADD = <KeyboardInput.NUMPAD_ADD: 94>#

NUMPAD_DEL = <KeyboardInput.NUMPAD_DEL: 90>#

NUMPAD_DIVIDE = <KeyboardInput.NUMPAD_DIVIDE: 91>#

NUMPAD_ENTER = <KeyboardInput.NUMPAD_ENTER: 95>#

NUMPAD_EQUAL = <KeyboardInput.NUMPAD_EQUAL: 96>#

NUMPAD_MULTIPLY = <KeyboardInput.NUMPAD_MULTIPLY: 92>#

NUMPAD_SUBTRACT = <KeyboardInput.NUMPAD_SUBTRACT: 93>#

NUM_LOCK = <KeyboardInput.NUM_LOCK: 65>#

O = <KeyboardInput.O: 33>#

P = <KeyboardInput.P: 34>#

PAGE_DOWN = <KeyboardInput.PAGE_DOWN: 60>#

PAGE_UP = <KeyboardInput.PAGE_UP: 59>#

PAUSE = <KeyboardInput.PAUSE: 67>#

PERIOD = <KeyboardInput.PERIOD: 5>#

PRINT_SCREEN = <KeyboardInput.PRINT_SCREEN: 66>#

Q = <KeyboardInput.Q: 35>#

R = <KeyboardInput.R: 36>#

RIGHT = <KeyboardInput.RIGHT: 55>#

RIGHT_ALT = <KeyboardInput.RIGHT_ALT: 103>#

RIGHT_BRACKET = <KeyboardInput.RIGHT_BRACKET: 47>#

RIGHT_CONTROL = <KeyboardInput.RIGHT_CONTROL: 102>#

RIGHT_SHIFT = <KeyboardInput.RIGHT_SHIFT: 101>#

RIGHT_SUPER = <KeyboardInput.RIGHT_SUPER: 104>#

S = <KeyboardInput.S: 37>#

SCROLL_LOCK = <KeyboardInput.SCROLL_LOCK: 64>#

SEMICOLON = <KeyboardInput.SEMICOLON: 17>#

SLASH = <KeyboardInput.SLASH: 6>#

SPACE = <KeyboardInput.SPACE: 1>#

T = <KeyboardInput.T: 38>#

TAB = <KeyboardInput.TAB: 50>#

U = <KeyboardInput.U: 39>#

UNKNOWN = <KeyboardInput.UNKNOWN: 0>#

UP = <KeyboardInput.UP: 58>#

V = <KeyboardInput.V: 40>#

W = <KeyboardInput.W: 41>#

X = <KeyboardInput.X: 42>#

Y = <KeyboardInput.Y: 43>#

Z = <KeyboardInput.Z: 44>#

property name#

property value#

class carb.input.Mouse#

class carb.input.MouseEvent#

property device#

property modifiers#

property mouse#

property normalized_coords#

property pixel_coords#

property scrollDelta#

property type#

class carb.input.MouseEventType#

Members:

LEFT_BUTTON_DOWN

LEFT_BUTTON_UP

MIDDLE_BUTTON_DOWN

MIDDLE_BUTTON_UP

RIGHT_BUTTON_DOWN

RIGHT_BUTTON_UP

MOVE

SCROLL

LEFT_BUTTON_DOWN = <MouseEventType.LEFT_BUTTON_DOWN: 0>#

LEFT_BUTTON_UP = <MouseEventType.LEFT_BUTTON_UP: 1>#

MIDDLE_BUTTON_DOWN = <MouseEventType.MIDDLE_BUTTON_DOWN: 2>#

MIDDLE_BUTTON_UP = <MouseEventType.MIDDLE_BUTTON_UP: 3>#

MOVE = <MouseEventType.MOVE: 6>#

RIGHT_BUTTON_DOWN = <MouseEventType.RIGHT_BUTTON_DOWN: 4>#

RIGHT_BUTTON_UP = <MouseEventType.RIGHT_BUTTON_UP: 5>#

SCROLL = <MouseEventType.SCROLL: 7>#

property name#

property value#

class carb.input.MouseInput#

Members:

LEFT_BUTTON

RIGHT_BUTTON

MIDDLE_BUTTON

FORWARD_BUTTON

BACK_BUTTON

SCROLL_RIGHT

SCROLL_LEFT

SCROLL_UP

SCROLL_DOWN

MOVE_RIGHT

MOVE_LEFT

MOVE_UP

MOVE_DOWN

COUNT

BACK_BUTTON = <MouseInput.BACK_BUTTON: 4>#

COUNT = <MouseInput.COUNT: 13>#

FORWARD_BUTTON = <MouseInput.FORWARD_BUTTON: 3>#

LEFT_BUTTON = <MouseInput.LEFT_BUTTON: 0>#

MIDDLE_BUTTON = <MouseInput.MIDDLE_BUTTON: 2>#

MOVE_DOWN = <MouseInput.MOVE_DOWN: 12>#

MOVE_LEFT = <MouseInput.MOVE_LEFT: 10>#

MOVE_RIGHT = <MouseInput.MOVE_RIGHT: 9>#

MOVE_UP = <MouseInput.MOVE_UP: 11>#

RIGHT_BUTTON = <MouseInput.RIGHT_BUTTON: 1>#

SCROLL_DOWN = <MouseInput.SCROLL_DOWN: 8>#

SCROLL_LEFT = <MouseInput.SCROLL_LEFT: 6>#

SCROLL_RIGHT = <MouseInput.SCROLL_RIGHT: 5>#

SCROLL_UP = <MouseInput.SCROLL_UP: 7>#

property name#

property value#

carb.input.acquire_input_interface( plugin_name: str = None, library_path: str = None, ) → carb.input.IInput#

carb.input.acquire_input_provider( plugin_name: str = None, library_path: str = None, ) → carb::input::InputProvider#

carb.input.get_action_mapping_desc_from_string( arg0: str, ) → carb.input.ActionMappingDesc#

carb.input.get_string_from_action_mapping_desc(*args, **kwargs)#

Overloaded function.

get_string_from_action_mapping_desc(arg0: carb.input.KeyboardInput, arg1: int) -> str
get_string_from_action_mapping_desc(arg0: carb.input.MouseInput, arg1: int) -> str
get_string_from_action_mapping_desc(arg0: carb.input.GamepadInput) -> str

carb.l10n#

pybind11 carb.l10n bindings

class carb.l10n.LanguageIdentifier#

class carb.l10n.LanguageTable#

carb.l10n.deregister_localization_for_client() → None#

Deregister the localization plugin for the current client.

This can be called to deregister the localization plugin for the current client, if carb::shutdownFramework will not be called.

carb.l10n.get_hash_from_key_string(arg0: str) → int#

Hash a keystring for localization.

This hashes a keystring that can be looked up with carb_localize_hashed(). Strings must be hashed before passing them into carb_localize_hashed(); this is done largely so that automated tools can easily find all of the localized strings in scripts by searching for this function name.

In cases where a string will be looked up many times, it is ideal to cache the hash returned, so that it is not recalculated excessively.

Parameters:: string – The keystring to hash. This must be a string. This must not be None.
Returns:: The hash for the string argument. This hash can be used in carb_localize_hashed().

carb.l10n.get_localized_string(arg0: str) → str#

Retrieve a string from the localization database, given its hash.

This function retrieves a localized string based on the hash of the keystring. This should be used on all strings found in the UI, so that they can automatically be shown in the correct language. Strings returned from this function should never be cached, so that changing the language at runtime will not result in stale strings being shown in the UI.

Parameters:

string – The keystring that identifies the set of localized strings to return. This will typically correspond to the US English string for this UI text. This string will be returned if there is no localization table entry for this key.

Returns:

The localized string for the input hash in the currently set language, if a string exists for that language.

If no localized string from the currently set language exists for the hash, the US English string will be returned.

If the hash is not found in the localization database, the string parameter will be returned. Alternatively, if a config setting is enabled, error messages will be returned in this case.

carb.l10n.get_localized_string_from_hash( id: int = 0, string: str = '{TRANSLATION NOT FOUND}', ) → str#

Retrieve a string from the localization database, given its hash.

This function retrieves a localized string based on the hash of the keystring. This should be used on all strings found in the UI, so that they can automatically be shown in the correct language. Strings returned from this function should never be cached, so that changing the language at runtime will not result in stale strings being shown in the UI.

Parameters:

id – A hash that was previously returned by hash_localization_string().
string – The keystring that was hashed with hash_localization_string(). This is passed to ensure that a readable string is returned if the hash is not found in the localization table.

Returns:

The localized string for the input hash in the currently set language, if a string exists for that language.

If no localized string from the currently set language exists for the hash, the US English string will be returned.

If the hash is not found in the localization database, the string parameter will be returned. Alternatively, if a config setting is enabled, error messages will be returned in this case.

carb.l10n.register_for_client() → None#

Register the l10n plugin for the current client.

This must be called before using any of the localization plugins, if carb::startupFramework() has not been called.

This use case is only encountered in the tests. Standard Carbonite applications call carb::startupFramework() so they should never have to call this.

If this is not called, the localization system will be non-functional.

carb.profiler#

class carb.profiler.FlowType#

Members:

BEGIN

END

BEGIN = <FlowType.BEGIN: 0>#

END = <FlowType.END: 1>#

property name#

property value#

class carb.profiler.IProfileMonitor#

get_last_profile_events( self: carb.profiler._profiler.IProfileMonitor, ) → carb.profiler._profiler.ProfileEvents#

mark_frame_end( self: carb.profiler._profiler.IProfileMonitor, ) → None#

class carb.profiler.IProfiler#

begin( self: carb.profiler._profiler.IProfiler, mask: int, name: str, ) → None#

end( self: carb.profiler._profiler.IProfiler, mask: int, ) → None#

ensure_thread( self: carb.profiler._profiler.IProfiler, ) → None#

Ensures that the profiler is aware of a Python thread.

If the profiler is already aware of the Python thread, there is no effect.

Parameters:: None
Returns:: None

flow( self: carb.profiler._profiler.IProfiler, arg0: int, arg1: carb.profiler._profiler.FlowType, arg2: int, arg3: str, ) → None#

frame( self: carb.profiler._profiler.IProfiler, arg0: int, arg1: str, ) → None#

get_capture_mask( self: carb.profiler._profiler.IProfiler, ) → int#

instant( self: carb.profiler._profiler.IProfiler, arg0: int, arg1: carb.profiler._profiler.InstantType, arg2: str, ) → None#

is_python_profiling_enabled( self: carb.profiler._profiler.IProfiler, ) → bool#

Returns whether Python cProfile-level profiling is enabled.

Returns:: True if Python function profiling is enabled, False otherwise.

set_capture_mask( self: carb.profiler._profiler.IProfiler, mask: int, ) → int#

set_python_profiling_enabled( self: carb.profiler._profiler.IProfiler, enable: bool, ) → None#

Enables or disables cProfile-level Python profiling.

Enabling this value causes every Python function call to be recorded through carb.profiler. As such, it can negatively affect performance and can lead to very large profiler files.

Only Python threads that carb.profiler is aware of will report to the profiler. Calling ensure_thread() will ensure that carb.profiler is aware of a Python thread.

Use is_python_profiling_enabled() to determine the current state of this value.

Parameters:: enable – True to enable the profiler or False to disable.
Returns:: None

shutdown(self: carb.profiler._profiler.IProfiler) → None#

startup(self: carb.profiler._profiler.IProfiler) → None#

value_float( self: carb.profiler._profiler.IProfiler, mask: int, value: float, name: str, ) → None#

value_int( self: carb.profiler._profiler.IProfiler, mask: int, value: int, name: str, ) → None#

value_uint( self: carb.profiler._profiler.IProfiler, mask: int, value: int, name: str, ) → None#

class carb.profiler.InstantType#

Members:

THREAD

PROCESS

PROCESS = <InstantType.PROCESS: 1>#

THREAD = <InstantType.THREAD: 0>#

property name#

property value#

class carb.profiler.ProfileEvents#

Profile Events holder

get_main_thread_id( self: carb.profiler._profiler.ProfileEvents, ) → int#

get_profile_events( self: carb.profiler._profiler.ProfileEvents, thread_id: int = 0, ) → tuple#

get_profile_thread_ids( self: carb.profiler._profiler.ProfileEvents, ) → tuple#

carb.profiler.acquire_profile_monitor_interface( plugin_name: str = None, library_path: str = None, ) → carb.profiler._profiler.IProfileMonitor#

carb.profiler.acquire_profiler_interface( plugin_name: str = None, library_path: str = None, ) → carb.profiler._profiler.IProfiler#

carb.profiler.begin(mask, name, stack_offset=0)#

carb.profiler.begin_with_location( mask: int, name: str, function: str = '', filepath: str = '', lineno: int = 0, ) → None#

carb.profiler.end(mask: int) → None#

carb.profiler.is_profiler_active() → bool#

carb.profiler.profile(func=None, mask=1, zone_name=None, add_args=False)#

Decorator to profile function call

Example:

import carb.profiler

@carb.profiler.profile
def foo():
    pass

# Or:
@carb.profiler.profile(mask=10, zone_name="Foonction", add_args=True)
def foo():
    pass

carb.profiler.supports_dynamic_source_locations() → bool#

carb.settings#

Bindings for carb::settings::ISettings interface. Settings is a runtime representation of typical configuration formats (like json, toml, xml), it is a nested dictionary of values.

class carb.settings.ChangeEventType#

Members:

CREATED : An Item was created

CHANGED : An Item was changed

DESTROYED : An Item was destroyed

CHANGED = <ChangeEventType.CHANGED: 1>#

CREATED = <ChangeEventType.CREATED: 0>#

DESTROYED = <ChangeEventType.DESTROYED: 2>#

property name#

property value#

class carb.settings.ISettings#

The Carbonite Settings interface

Carbonite settings are built on top of the carb.dictionary interface (which is also required in order to use this interface). Many dictionary functions are replicated in settings, but explicitly use the settings database instead of a generic carb.dictionary.Item object.

carb.settings uses keys (or paths) that start with an optional forward-slash and are forward-slash separated (example: “/log/level”). The settings database exists as a root-level carb.dictionary.Item (of type ItemType.DICTIONARY) that is created and maintained by the carb.settings system (typically through the carb.settings.plugin plugin). The root level settings carb.dictionary.Item is accessible through get_settings_dictionary().

Portions of the settings database hierarchy can be subscribed to with subscribe_to_tree_change_events() or individual keys may be subscribed to with subscribe_to_tree_change_events().

create_dictionary_from_settings( self: carb.settings._settings.ISettings, path: str = '', ) → carb.dictionary._dictionary.Item#

Takes a snapshot of a portion of the setting database as a dictionary.Item.

Parameters:: path – An optional path from root to access. “/” or “” is interpreted to be the settings database root.

destroy_item( self: carb.settings._settings.ISettings, arg0: str, ) → None#

Destroys the item at the given path.

Any objects that reference the given path become invalid and their use is undefined behavior.

Parameters:: path – Settings database key path (i.e. “/log/level”).

get( self: carb.settings._settings.ISettings, path: str, ) → object#

Retrieve the stored value at the supplied path as a Python object.

An array value will be returned as a list. If the value does not exist, None will be returned.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: A Python object representing the stored value.

get_as_bool( self: carb.settings._settings.ISettings, arg0: str, ) → bool#

Attempts to get the supplied item as a boolean value, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: a boolean value representing the stored value. If conversion fails, False is returned.
Return type:: Boolean

get_as_float( self: carb.settings._settings.ISettings, arg0: str, ) → float#

Attempts to get the supplied item as a floating-point value, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: a floating-point value representing the stored value. If conversion fails, 0.0 is returned.
Return type:: Float

get_as_int( self: carb.settings._settings.ISettings, arg0: str, ) → int#

Attempts to get the supplied item as an integer, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: an integer value representing the stored value. If conversion fails, 0 is returned.
Return type:: Integer

get_as_string( self: carb.settings._settings.ISettings, arg0: str, ) → str#

Attempts to get the supplied item as a string value, either directly or via conversion.

Parameters:: path – Settings database key path (i.e. “/log/level”).
Returns:: a string value representing the stored value. If conversion fails, “” is returned.
Return type:: String

get_settings_dictionary( self: carb.settings._settings.ISettings, path: str = '', ) → carb.dictionary._dictionary.Item#

Access the setting database as a dictionary.Item

Accesses the setting database as a dictionary.Item, which allows use of carb.dictionary functions directly.

WARNING: The root dictionary.Item is owned by carb.settings and must not be altered or destroyed.

Parameters:: path – An optional path from root to access. “/” or “” is interpreted to be the settings database root.

initialize_from_dictionary( self: carb.settings._settings.ISettings, arg0: carb.dictionary._dictionary.Item, ) → None#

Performs a one-time initialization from a given dictionary.Item.

NOTE: This function may only be called once. Subsequent calls will result in an error message logged.

Parameters:: dictionary – A dictionary.Item to initialize the settings database from. The items are copied into the root of the settings database.

is_accessible_as( self: carb.settings._settings.ISettings, arg0: carb.dictionary._dictionary.ItemType, arg1: str, ) → bool#

Checks if the item could be accessible as the provided type, either directly or via a cast.

Parameters:

itemType – carb.dictionary.ItemType to check for.
path – Settings database key path (i.e. “/log/level”).

Returns:

True if the item is accessible as the provided type; False otherwise.

Return type:

boolean

set( self: carb.settings._settings.ISettings, path: str, value: object, ) → None#

Sets the given value at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – A Python object. The carb.dictionary.ItemType is inferred from the type of the object; if the type is not supported, the value is ignored. Both tuples and lists are treated as arrays (a special kind of ItemType.DICTIONARY).

set_bool( self: carb.settings._settings.ISettings, arg0: str, arg1: bool, ) → None#

Sets the boolean value at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – A boolean value to store.

set_bool_array( self: carb.settings._settings.ISettings, arg0: str, arg1: List[bool], ) → None#

Sets the given array at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – A tuple or list of boolean values.

set_default( self: carb.settings._settings.ISettings, path: str, value: object, ) → None#

set_default_bool( self: carb.settings._settings.ISettings, arg0: str, arg1: bool, ) → None#

Sets a value at the given path, if and only if one does not already exist.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path if a value does not already exist there.

set_default_float( self: carb.settings._settings.ISettings, arg0: str, arg1: float, ) → None#

Sets a value at the given path, if and only if one does not already exist.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path if a value does not already exist there.

set_default_int( self: carb.settings._settings.ISettings, arg0: str, arg1: int, ) → None#

Sets a value at the given path, if and only if one does not already exist.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path if a value does not already exist there.

set_default_string( self: carb.settings._settings.ISettings, arg0: str, arg1: str, ) → None#

Sets a value at the given path, if and only if one does not already exist.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – Value that will be stored at the given path if a value does not already exist there.

set_float( self: carb.settings._settings.ISettings, arg0: str, arg1: float, ) → None#

Sets the floating-point value at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – A floating-point value to store.

set_float_array( self: carb.settings._settings.ISettings, arg0: str, arg1: List[float], ) → None#

Sets the given array at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – A tuple or list of floating-point values.

set_int( self: carb.settings._settings.ISettings, arg0: str, arg1: int, ) → None#

Sets the integer value at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – An integer value to store.

set_int_array( self: carb.settings._settings.ISettings, arg0: str, arg1: List[int], ) → None#

Sets the given array at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – A tuple or list of integer values.

set_string( self: carb.settings._settings.ISettings, arg0: str, arg1: str, ) → None#

Sets the string value at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
value – A string value.

set_string_array( self: carb.settings._settings.ISettings, arg0: str, arg1: List[str], ) → None#

Sets the given array at the supplied path.

Parameters:

path – Settings database key path (i.e. “/log/level”).
array – A tuple or list of strings.

subscribe_to_node_change_events( self: carb.settings._settings.ISettings, arg0: str, arg1: Callable[[carb.dictionary._dictionary.Item, carb.settings._settings.ChangeEventType], None], ) → carb.settings._settings.SubscriptionId#

Subscribes to node change events about a specific item.

When finished with the subscription, call unsubscribe_to_change_events().

Parameters:

path – Settings database key path (i.e. “/log/level”) to subscribe to.
eventFn – A function that is called for each change event.

subscribe_to_tree_change_events( self: carb.settings._settings.ISettings, arg0: str, arg1: Callable[[carb.dictionary._dictionary.Item, carb.dictionary._dictionary.Item, carb.settings._settings.ChangeEventType], None], ) → carb.settings._settings.SubscriptionId#

Subscribes to change events for all items in a subtree.

When finished with the subscription, call unsubscribe_to_change_events().

Parameters:

path – Settings database key path (i.e. “/log/level”) to subscribe to.
eventFn – A function that is called for each change event.

unsubscribe_to_change_events( self: carb.settings._settings.ISettings, id: carb.settings._settings.SubscriptionId, ) → None#

Unsubscribes from change events.

Parameters:: id – The handle returned from subscribe_to_tree_change_events() or subscribe_to_node_change_events().

update( self: carb.settings._settings.ISettings, arg0: str, arg1: carb.dictionary._dictionary.Item, arg2: str, arg3: object, ) → None#

Merges the source dictionary.Item into the settings database.

Destination path need not exist and missing items in the path will be created as ItemType.DICTIONARY.

Parameters:

path – Settings database key path (i.e. “/log/level”). Used as the destination location within the setting database. “/” is considered to be the root.
dictionary – A dictionary.Item used as the base of the items to merge into the setting database.
dictionaryPath – A child path of dictionary to use as the root for merging. May be None or an empty string in order to use dictionary directly as the root.
updatePolicy – One of dictionary.UpdateAction to use as the policy for updating.

class carb.settings.SubscriptionId#: Representation of a subscription

carb.settings.acquire_settings_interface( plugin_name: str = None, library_path: str = None, ) → carb.settings._settings.ISettings#

carb.settings.get_settings() → ISettings#: Returns cached carb.settings.ISettings interface (shorthand).

carb.settings.get_settings_interface() → ISettings#: Returns cached carb.settings.ISettings interface

carb.settings.lru_cache(maxsize=128, typed=False)#

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

carb.simplegui#

class carb.simplegui.Condition#

Members:

ALWAYS

APPEARING

FIRST_USE_EVER

ONCE

ALWAYS = <Condition.ALWAYS: 1>#

APPEARING = <Condition.APPEARING: 8>#

FIRST_USE_EVER = <Condition.FIRST_USE_EVER: 4>#

ONCE = <Condition.ONCE: 2>#

property name#

property value#

class carb.simplegui.ISimpleGui#

begin( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: bool, arg2: int, ) → tuple#

begin_child( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: carb._carb.Float2, arg2: bool, arg3: int, ) → bool#

begin_popup_modal( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: bool, arg2: int, ) → bool#

bullet(self: carb.simplegui._simplegui.ISimpleGui) → None#

button( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → bool#

checkbox( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: bool, ) → tuple#

close_current_popup( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

collapsing_header( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: int, ) → bool#

color_edit3( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: carb._carb.Float3, ) → tuple#

color_edit4( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: carb._carb.Float4, ) → tuple#

combo( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: int, arg2: List[str], ) → tuple#

dock_builder_dock_window( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: int, ) → None#

dummy( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb._carb.Float2, ) → None#

end(self: carb.simplegui._simplegui.ISimpleGui) → None#

end_child( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

end_popup( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

get_display_size( self: carb.simplegui._simplegui.ISimpleGui, ) → carb._carb.Float2#

indent(self: carb.simplegui._simplegui.ISimpleGui) → None#

input_float( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: float, arg2: float, ) → tuple#

input_int( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: int, arg2: int, ) → tuple#

input_text( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: str, arg2: int, ) → tuple#

menu_item_ex( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: str, arg2: bool, arg3: bool, ) → tuple#

open_popup( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → None#

plot_lines( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: List[float], arg2: int, arg3: int, arg4: str, arg5: float, arg6: float, arg7: carb._carb.Float2, arg8: int, ) → None#

pop_id(self: carb.simplegui._simplegui.ISimpleGui) → None#

pop_item_width( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

pop_style_color( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

pop_style_var( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

progress_bar( self: carb.simplegui._simplegui.ISimpleGui, arg0: float, arg1: carb._carb.Float2, arg2: str, ) → None#

push_id_int( self: carb.simplegui._simplegui.ISimpleGui, arg0: int, ) → None#

push_id_string( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → None#

push_item_width( self: carb.simplegui._simplegui.ISimpleGui, arg0: float, ) → None#

push_style_color( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb::simplegui::StyleColor, arg1: carb._carb.Float4, ) → None#

push_style_var_float( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb::simplegui::StyleVar, arg1: float, ) → None#

push_style_var_float2( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb::simplegui::StyleVar, arg1: carb._carb.Float2, ) → None#

same_line( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

same_line_ex( self: carb.simplegui._simplegui.ISimpleGui, pos_x: float = 0.0, spacing_w: float = -1.0, ) → None#

separator( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

set_display_size( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb._carb.Float2, ) → None#

set_next_window_pos( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb._carb.Float2, arg1: carb.simplegui._simplegui.Condition, arg2: carb._carb.Float2, ) → None#

set_next_window_size( self: carb.simplegui._simplegui.ISimpleGui, arg0: carb._carb.Float2, arg1: carb.simplegui._simplegui.Condition, ) → None#

set_scroll_here_y( self: carb.simplegui._simplegui.ISimpleGui, arg0: float, ) → None#

show_demo_window( self: carb.simplegui._simplegui.ISimpleGui, arg0: bool, ) → None#

slider_float( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: float, arg2: float, arg3: float, ) → tuple#

slider_int( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, arg1: int, arg2: int, arg3: int, ) → tuple#

small_button( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → bool#

spacing(self: carb.simplegui._simplegui.ISimpleGui) → None#

text( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → None#

text_unformatted( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → None#

text_wrapped( self: carb.simplegui._simplegui.ISimpleGui, arg0: str, ) → None#

tree_node_ptr( self: carb.simplegui._simplegui.ISimpleGui, arg0: int, arg1: str, ) → bool#

tree_pop( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

unindent( self: carb.simplegui._simplegui.ISimpleGui, ) → None#

carb.simplegui.acquire_simplegui_interface( plugin_name: str = None, library_path: str = None, ) → carb.simplegui._simplegui.ISimpleGui#

carb.simplegui.get_simplegui() → ISimpleGui#: Returns cached carb.simplegui.ISimpleGui interface (shorthand).

carb.simplegui.get_simplegui_interface() → ISimpleGui#: Returns cached carb.simplegui.ISimpleGui interface.

carb.simplegui.lru_cache(maxsize=128, typed=False)#

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

carb.tokens#

Bindings for carb::tokens::ITokens interface. It is used for storing tokens and resolving strings containing them.

class carb.tokens.ITokens#

The Carbonite Tokens Interface

Interface for storing tokens and resolving strings containing them. Tokens are string pairs {name, value} that can be referenced in a string as “some text ${token_name} some other text”, where the token name starts with a sequence “${” and end with a first closing “}”.

If a token with the name <token_name> has a defined value, then it will be substituted with its value. If the token does not have a defined value, an empty string will be used for the replacement. This interface will use the ISetting interface, if available, as storage and in such case tokens will be stored under the ‘/app/tokens’ node.

Note: The “$” symbol is considered to be special by the tokenizer and should be escaped by doubling it (“$” -> “$$”) in order to be processed as just a symbol “$” Ex: “some text with $ sign” -> “some text with $$ sign”

Single unescaped “$” signs are considered to be a bad practice to be used for token resolution but they are acceptable and will be resolved into single “$” signs and no warning will be given about it.

Ex:: “$” -> “$”, “$$” -> “$”, “$$$” -> “$$”

It’s better to use the helper function “escapeString” from the “TokensUtils.h” to produce a string that doesn’t have any parts that could participate in tokenization. As a token name start with “${” and ends with the first encountered “}” it can contain “$” (same rules about escaping it apply) and “{” characters, however such cases will result in a warning being output to the log. Ex: for the string “${bar$${}” the token resolution process will consider the token name to be “bar${” (note that “$$” is reduced into a single “$”) and a warning will be outputted into the log.

Tokens are resolved recursively unless an error occurs. For instance:

tokens.set_value("a", "${b}");
tokens.set_value("b", "${c}");
tokens.set_value("c", "hello ${d}");
tokens.set_value("d", "world");

tokens.resolve("${a}"); # will return "hello world"

Environment variables are automatically available as tokens, if defined. These are specified with the text ${env:<var name>} where <var name> is the name of the environment variable. The env: prefix is a reserved name, so any call to set_value() or set_initial_value() with a name that starts with env: will be rejected. The environment variable is read when needed and not cached in any way. An undefined environment variable behaves as an undefined token.

Thread Safety: the interface’s functions are not thread safe. It is responsibility of the user to use all necessary synchronization mechanisms if needed. All data passed into a plugin’s function must be valid for the duration of the function call.

exists(self: carb.tokens._tokens.ITokens, name: str) → bool#

Checks for the existence of a token.

Parameters:: name – Token name not enclosed in “${” and “}”.
Returns:: True if the token with the specified name exists; False if the token name does not exist or an error occurred.
Return type:: boolean

remove_token( self: carb.tokens._tokens.ITokens, name: str, ) → bool#

Delete a token.

Parameters:: name – Token name not enclosed in “${” and “}”.
Returns:: True if the operation was successful or the token did not exist. False if an error occurred.
Return type:: boolean

resolve( self: carb.tokens._tokens.ITokens, str: str, flags: int = 0, ) → str#

Tries to resolve all tokens in the string buffer and returns the result.

Parameters:

str – The string to resolve.
flags – (optional, defaults to RESOLVE_FLAG_NONE) Flags that modify the token resolution process.

Returns:

The resolved string, or None if an error occurs.

Return type:

string

set_initial_value( self: carb.tokens._tokens.ITokens, name: str, value: str, ) → None#

Creates a token with the given name and value if it was non-existent. Otherwise does nothing.

Parameters:

name – Token name not enclosed in “${” and “}”.
value – Value to assign if the token does not previously exist.

set_value( self: carb.tokens._tokens.ITokens, name: str, value: str, ) → bool#

Sets a new value for the specified token, if the token didn’t exist it will be created.

Note: if the value is null then the token will be removed (see also: remove_token function). In this case true is returned if the token was successfully deleted or didn’t exist.

Parameters:

name – Token name not enclosed in “${” and “}”.
value – New value for the token.

Returns:

True if the operation was successful, False if an error occurred.

Return type:

boolean

carb.tokens.acquire_tokens_interface( plugin_name: str = None, library_path: str = None, ) → carb.tokens._tokens.ITokens#

carb.tokens.get_tokens_interface() → ITokens#: Returns cached carb.tokens.ITokens interface

carb.variant#

class carb.variant.IVariant#

carb.variant.acquire_variant_interface( plugin_name: str = None, library_path: str = None, ) → carb.variant._variant.IVariant#

carb.variant.get_variant() → IVariant#: Returns cached carb.variant.IVariant interface (shorthand).

carb.variant.get_variant_interface() → IVariant#: Returns cached carb.variant.IVariant interface

carb.variant.lru_cache(maxsize=128, typed=False)#

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

carb.windowing#

pybind11 carb.windowing bindings

class carb.windowing.Cursor#

class carb.windowing.CursorMode#

Members:

NORMAL

HIDDEN

DISABLED

DISABLED = <CursorMode.DISABLED: 2>#

HIDDEN = <CursorMode.HIDDEN: 1>#

NORMAL = <CursorMode.NORMAL: 0>#

property name#

property value#

class carb.windowing.CursorStandardShape#

Members:

ARROW

IBEAM

CROSSHAIR

HAND

HORIZONTAL_RESIZE

VERTICAL_RESIZE

ARROW = <CursorStandardShape.ARROW: 0>#

CROSSHAIR = <CursorStandardShape.CROSSHAIR: 2>#

HAND = <CursorStandardShape.HAND: 3>#

HORIZONTAL_RESIZE = <CursorStandardShape.HORIZONTAL_RESIZE: 4>#

IBEAM = <CursorStandardShape.IBEAM: 1>#

VERTICAL_RESIZE = <CursorStandardShape.VERTICAL_RESIZE: 5>#

property name#

property value#

class carb.windowing.GLContext#

class carb.windowing.IGLContext#

create_context_opengl( self: carb.windowing.IGLContext, width: int, height: int, ) → carb.windowing.GLContext#

create_context_opengles( self: carb.windowing.IGLContext, width: int, height: int, ) → carb.windowing.GLContext#

destroy_context( self: carb.windowing.IGLContext, arg0: carb.windowing.GLContext, ) → None#

make_context_current( self: carb.windowing.IGLContext, arg0: carb.windowing.GLContext, ) → None#

class carb.windowing.IWindowing#

create_cursor( self: carb.windowing.IWindowing, arg0: carb.windowing.Image, arg1: int, arg2: int, ) → carb.windowing.Cursor#

create_cursor_standard( self: carb.windowing.IWindowing, arg0: carb.windowing.CursorStandardShape, ) → carb.windowing.Cursor#

create_window( self: carb.windowing.IWindowing, width: int, height: int, title: str, fullscreen: bool, hints: int = 0, ) → carb.windowing.Window#

destroy_cursor( self: carb.windowing.IWindowing, arg0: carb.windowing.Cursor, ) → None#

destroy_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

focus_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

get_clipboard( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → str#

get_cursor_mode( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb.windowing.CursorMode#

get_cursor_position( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb._carb.Int2#

get_input_mode( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb.windowing.InputMode, ) → bool#

get_keyboard( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb.input.Keyboard#

get_monitor_position( self: carb.windowing.IWindowing, arg0: carb.windowing.Monitor, ) → carb._carb.Int2#

get_monitor_work_area( self: carb.windowing.IWindowing, arg0: carb.windowing.Monitor, ) → tuple#

get_monitors(self: carb.windowing.IWindowing) → tuple#

get_mouse( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb.input.Mouse#

get_native_display( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → capsule#

get_native_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → capsule#

get_window_height( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → int#

get_window_opacity( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → float#

get_window_position( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb._carb.Int2#

get_window_user_pointer( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → capsule#

get_window_width( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → int#

hide_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

is_window_focused( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → bool#

is_window_fullscreen( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → bool#

is_window_maximized( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → bool#

is_window_minimized( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → bool#

maximize_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

minimize_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

poll_events(self: carb.windowing.IWindowing) → None#

resize_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: int, arg2: int, ) → None#

restore_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

set_clipboard( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: str, ) → None#

set_cursor( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb.windowing.Cursor, ) → None#

set_cursor_mode( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb.windowing.CursorMode, ) → None#

set_cursor_position( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb._carb.Int2, ) → None#

set_input_mode( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb.windowing.InputMode, arg2: bool, ) → None#

set_window_content_scale( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → carb._carb.Float2#

set_window_fullscreen( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: bool, ) → None#

set_window_icon( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb.windowing.Image, ) → None#

set_window_opacity( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: float, ) → None#

set_window_position( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: carb._carb.Int2, ) → None#

set_window_should_close( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: bool, ) → None#

set_window_title( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: str, ) → None#

set_window_user_pointer( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, arg1: capsule, ) → None#

should_window_close( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → bool#

show_window( self: carb.windowing.IWindowing, arg0: carb.windowing.Window, ) → None#

translate_key( self: carb.windowing.IWindowing, arg0: carb.input.KeyboardInput, ) → carb.input.KeyboardInput#

update_input_devices( self: carb.windowing.IWindowing, ) → None#

wait_events(self: carb.windowing.IWindowing) → None#

class carb.windowing.Image#

class carb.windowing.InputMode#

Members:

STICKY_KEYS

STICKY_MOUSE_BUTTONS

LOCK_KEY_MODS

RAW_MOUSE_MOTION

LOCK_KEY_MODS = <InputMode.LOCK_KEY_MODS: 2>#

RAW_MOUSE_MOTION = <InputMode.RAW_MOUSE_MOTION: 3>#

STICKY_KEYS = <InputMode.STICKY_KEYS: 0>#

STICKY_MOUSE_BUTTONS = <InputMode.STICKY_MOUSE_BUTTONS: 1>#

property name#

property value#

class carb.windowing.Monitor#

class carb.windowing.Window#

carb.windowing.acquire_gl_context_interface( plugin_name: str = None, library_path: str = None, ) → carb.windowing.IGLContext#

carb.windowing.acquire_windowing_interface( plugin_name: str = None, library_path: str = None, ) → carb.windowing.IWindowing#

omni package#

omni.core#

class omni.core.Float2#

Helper struct to represent a single 2-space vector of floating point values. Each member of the struct can be accessed in multiple ways including an array and direct accessors known by multiple names. Objects of this struct are guaranteed to be only as large as two 32-bit floating point values.

property h#: /< Provides access to the first data member as a height value.

property s#: /< Provides access to the first data member as an S texture coordinate.

property t#: /< Provides access to the first data member as an T texture coordinate.

property u#: /< Provides access to the first data member as a U texture coordinate.

property v#: /< Provides access to the first data member as a V texture coordinate.

property w#: /< Provides access to the first data member as a width value.

property x#: Provides access to the first data member as a Cartesian X coordinate.

property y#: Provides access to the first data member as a Cartesian Y coordinate.

class omni.core.IObject#

class omni.core.ITypeFactory#

A mapping from type id’s to implementations.

This object maps type id’s to concrete implementations. The type id’s can represent interface ids or implementation ids.

Register types with registerInterfaceImplementationsFromModule() and registerInterfaceImplementations().

Instantiate types with omni::core::createType(). This is the primary way Omniverse applications are able to instantiate concrete implementations of @rstref{ABI-safe <abi-compatibility>} interfaces. See omni::core::createType() for a helpful wrapper around omni::core::ITypeFactory::createType().

In practice, there will be a single ITypeFactory active in the process space (accessible via omniGetTypeFactoryWithoutAcquire()). However, @ref omni::core::ITypeFactory is not inherently a singleton, and as such multiple instantiations of the interface may exists. This can be used to create private type trees.

Unless otherwise noted, all methods in this interface are thread safe.

get_type_id_name( self: omni.core._core._ITypeFactory, id: int, ) → str#

Maps a type id back to its type name.

The memory returned is valid for the lifetime of ITypeFactory

Returns nullptr if id has never been registered. Types that have been registered, and then unregistered, will still have a valid string returned from this method.

This method is thread safe.

register_interface_implementations_from_module( self: omni.core._core.ITypeFactory, module_name: str, flags: int, ) → int#

Registers types from the given module.

If the module is currently loaded, it will not be reloaded and kResultSuccess is returned.

Modules (e.g. .dll or .so) may contain one or many implementations of one or many interfaces. When registering a module with the type factory, a function, whose name is described by ‘kModuleGetExportsName’, is found and invoked. Let’s assume the exported function name is “omniModuleGetExports”.

“omniModuleGetExports” returns a key/value database of the module’s capabilities and the module’s requirements. Some things to note about this database:

The module’s requirements can be marked as optional.

The module’s capabilities can be ignored by ITypeFactory.

These properties allow ITypeFactory and the module to find an intersection of desired functionality in a data driven manner. If one party’s required needs are not met, the module fails to load (e.g. an appropriate omni::core::Result is returned).

It is expected the module has entries in the key/value database describing the functions ITypeFactory should call during the loading process. The most important of these entries is the one defined by OMNI_MODULE_ON_MODULE_LOAD(), which points to the function ITypeFactory should call to get a list of implementations in the module. ITypeFactory invokes exports from the module in the following pattern:

.------------------------------------------------------------------------------------------------------------.
|                                               -> Time ->                                                   |
|------------------------------------------------------------------------------------------------------------|
| omniModuleGetExports | onLoad (req.) | onStarted (optional) | onCanUnload (optional) | onUnload (optional) |
|                      |               | impl1->createFn      |                        |                     |
|                      |               | impl2->createFn      |                        |                     |
|                      |               | impl1->createFn      |                        |                     |
\------------------------------------------------------------------------------------------------------------/

Above, functions in the same column can be called concurrently. It’s up to the module to make sure such call patterns are thread safe within the module.

onCanUnload and createFn can be called multiple times. All other functions are called once during the lifecycle of a module.

see omni/core/ModuleExports.h. see onModuleLoadFn see onModuleStartedFn see onModuleCanUnloadFn see onModuleUnloadFn

The module can be explicitly unloaded with unregisterInterfaceImplementationsFromModule().

Upon destruction of this ITypeFactory, unregisterInterfaceImplementationsFromModule is called for each loaded module. If the ITypeFactory destructor’s call to unregisterInterfaceImplementationsFromModule fails to safely unload a module (via the module’s onModuleCanUnload and onModuleUnload), an attempt will be made to forcefully/unsafely unload the module.

The given module name must not be nullptr.

This method is thread safe. Modules can be loaded in parallel.

returns Returns kResultSuccess if the module is loaded (either due to this function or a previous call). Otherwise, an error is returned.

set_interface_defaults( self: omni.core._core.ITypeFactory, interface_id: int, impl_id: int, module_name: str, impl_version: int, ) → None#

Sets the implementation matching constraints for the given interface id.

See omni::core::ITypeFactory_abi::createType_abi() for how these constraints are used.

moduleName can be nullptr.

if implVersion is 0 and implId is an implementation id, the implementation with the highest version is chosen.

This method is thread safe.

unregister_interface_implementations_from_module( self: omni.core._core.ITypeFactory, module_name: str, ) → int#

Unregisters all types registered from the given module.

Unregistering a module may fail if the module does not belief it can safely be unloaded. This is determined by OMNI_MODULE_ON_MODULE_CAN_UNLOAD().

If unregistration does succeed, the given module will be unloaded from the process space.

Upon destruction of this ITypeFactory, unregisterInterfaceImplementationsFromModule is called for each loaded module. If the ITypeFactory destructor’s call to unregisterInterfaceImplementationsFromModule fails to safely unload a module (via the module’s onModuleCanUnload and onModuleUnload), an attempt will be made to forcefully/unsafely unload the module.

The given module name must not be nullptr.

This method is thread safe.

returns Returns kResultSuccess if the module wasn’t already loaded or if this method successfully unloaded the module. Return an error code otherwise.

class omni.core.Int2#

Helper struct to represent a single 2-space vector of signed integers. Each member of the struct can be accessed in multiple ways including an array and direct accessors known by multiple names. Objects of this struct are guaranteed to be only as large as two 32-bit signed integers.

property h#: /< Provides access to the first data member as a height value.

property s#: /< Provides access to the first data member as an S texture coordinate.

property t#: /< Provides access to the first data member as an T texture coordinate.

property u#: /< Provides access to the first data member as a U texture coordinate.

property v#: /< Provides access to the first data member as a V texture coordinate.

property w#: /< Provides access to the first data member as a width value.

property x#: Provides access to the first data member as a Cartesian X coordinate.

property y#: Provides access to the first data member as a Cartesian Y coordinate.

class omni.core.Result#

Error code for the result of an operation.

The numeric encoding for values follows Microsoft’s <a href=”https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a”> HRESULT</a> scheme. Many values are direct copies of those from the Windows API, such as kResultNotImplemented. Codes which are NVIDIA-provided, will have the mask 0xa4310000. This comes from setting the “customer bit” (bit at most-significant index 2) and having a “facility” (bits from index 5-15) of 0b10000110001 aka 0x431 (which is "NVDA" in Morse Code).

Members:

SUCCESS : Operation successful. No error occurred.

NOT_IMPLEMENTED : The feature or method was not implemented. It might be at some point in the future.

OPERATION_ABORTED : The operation was aborted.

FAIL : The operation failed. * Decimal Value: -2147467259

NOT_FOUND : The item was not found. * Decimal Value: -2147024894

ACCESS_DENIED : Access has been denied for this operation.

OUT_OF_MEMORY : A system is out of memory. This does not necessarily mean resident memory has been exhausted (although it can), as this code can be used to special conditions such as exhausting graphics memory or running out of a specific memory pool. It can also indicate that an allocation would have been too big and failed ahead of time.

NOT_SUPPORTED : The operation is not supported. * Decimal Value: -2147024846

INVALID_ARGUMENT : One or more of the arguments passed to a given function was invalid.

INVALID_STATE : The system is in an invalid state to perform the operation. This is distinct from kResultInvalidOperation in that it covers situations like “system is not yet started” or “file is closed.” * Decimal Value: -2147024892

VERSION_CHECK_FAILURE : Version check failure. * Decimal Value: -2147024253

VERSION_PARSE_ERROR : Failed to parse the version. * Decimal Value: -2147024119

INSUFFICIENT_BUFFER : Insufficient buffer. * Decimal Value: -2147024774

TRY_AGAIN : Try the operation again.

INTERRUPTED : An operation was interrupted. An “interruption” happens in cases where the operation did not complete successfully due to an outside system (such as a timer) interrupting it. For example, a function Result wait_for(duration d) might give kResultSuccess when function returns because the duration expired and kResultInterrupted if the system is shutting down.

NO_INTERFACE : Interface not implemented. * Decimal Value: -2147467262

NULL_POINTER : Pointer is null.

ALREADY_EXISTS : Object already exists.

INVALID_OPERATION : The operation was not valid for the target. For example, attempting to perform a write operation on a read-only file would result in this error.

NO_MORE_ITEMS : No more items to return. This is meant for things like reader queues when they have run out of data and will never have more data. For cases where something like an async queue being temporarily empty, use kResultTryAgain.

INVALID_INDEX : Invalid index.

NOT_ENOUGH_DATA : Not enough data.

TOO_MUCH_DATA : Too much data.

INVALID_DATA_TYPE : Invalid data type. This is used in cases where a specific type of data is requested, but that is not the data which the receiver has.

INVALID_DATA_SIZE : Invalid data size. This arises when the correct type of data is requested, but the requester believes the data size is different from the receiver. The cause of this is typically a version mismatch.

TIMED_OUT : Timed out.

WOULD_BLOCK : Would block.

ACCESS_DENIED = <Result.ACCESS_DENIED: -2147024891>#

ALREADY_EXISTS = <Result.ALREADY_EXISTS: -2147286960>#

FAIL = <Result.FAIL: -2147467259>#

INSUFFICIENT_BUFFER = <Result.INSUFFICIENT_BUFFER: -2147024774>#

INTERRUPTED = <Result.INTERRUPTED: -1540292607>#

INVALID_ARGUMENT = <Result.INVALID_ARGUMENT: -2147024809>#

INVALID_DATA_SIZE = <Result.INVALID_DATA_SIZE: -2144272372>#

INVALID_DATA_TYPE = <Result.INVALID_DATA_TYPE: -2144272373>#

INVALID_INDEX = <Result.INVALID_INDEX: -2146889720>#

INVALID_OPERATION = <Result.INVALID_OPERATION: -2147020579>#

INVALID_STATE = <Result.INVALID_STATE: -2147024892>#

NOT_ENOUGH_DATA = <Result.NOT_ENOUGH_DATA: -2144796415>#

NOT_FOUND = <Result.NOT_FOUND: -2147024894>#

NOT_IMPLEMENTED = <Result.NOT_IMPLEMENTED: -2147467263>#

NOT_SUPPORTED = <Result.NOT_SUPPORTED: -2147024846>#

NO_INTERFACE = <Result.NO_INTERFACE: -2147467262>#

NO_MORE_ITEMS = <Result.NO_MORE_ITEMS: -2146893782>#

NULL_POINTER = <Result.NULL_POINTER: -2147467261>#

OPERATION_ABORTED = <Result.OPERATION_ABORTED: -2147467260>#

OUT_OF_MEMORY = <Result.OUT_OF_MEMORY: -2147024882>#

SUCCESS = <Result.SUCCESS: 0>#

TIMED_OUT = <Result.TIMED_OUT: -1540282548>#

TOO_MUCH_DATA = <Result.TOO_MUCH_DATA: -2144796414>#

TRY_AGAIN = <Result.TRY_AGAIN: -2147020693>#

VERSION_CHECK_FAILURE = <Result.VERSION_CHECK_FAILURE: -2147024253>#

VERSION_PARSE_ERROR = <Result.VERSION_PARSE_ERROR: -2147024119>#

WOULD_BLOCK = <Result.WOULD_BLOCK: -1540282573>#

property name#

property value#

class omni.core.TypeFactoryLoadFlags#

Base type for the flags used when registering plugins or implementations with the type factory. These are used to modify how the plugin or implementation is registered. No flags are currently defined. These flags will all have the prefix fTypeFactoryFlag.

Members:

NONE : Flag to indicate that no special change in behavior should be used when registering a plugin or implementation.

NONE = <TypeFactoryLoadFlags.NONE: 0>#

property name#

property value#

class omni.core.UInt2#

Helper struct to represent a single 2-space vector of unsigned integers. Each member of the struct can be accessed in multiple ways including an array and direct accessors known by multiple names. Objects of this struct are guaranteed to be only as large as two 32-bit unsigned integers.

property h#: /< Provides access to the first data member as a height value.

property s#: /< Provides access to the first data member as an S texture coordinate.

property t#: /< Provides access to the first data member as an T texture coordinate.

property u#: /< Provides access to the first data member as a U texture coordinate.

property v#: /< Provides access to the first data member as a V texture coordinate.

property w#: /< Provides access to the first data member as a width value.

property x#: Provides access to the first data member as a Cartesian X coordinate.

property y#: Provides access to the first data member as a Cartesian Y coordinate.

omni.core.create_type( type_id: str, module_name: str = None, version: int = 0, ) → omni.core._core.IObject#

omni.core.register_module(module_name: str, flags: int = 0) → int#

omni.experimental.url#

omni.ext#

This module contains bindings to C++ omni::ext::IExtensions interface. Extension system of Omniverse Kit.

class omni.ext.DownloadState#

Index/Extension Download States.

Members:

DOWNLOADING

DOWNLOAD_SUCCESS

DOWNLOAD_FAILURE

DOWNLOADING = <DownloadState.DOWNLOADING: 0>#

DOWNLOAD_FAILURE = <DownloadState.DOWNLOAD_FAILURE: 2>#

DOWNLOAD_SUCCESS = <DownloadState.DOWNLOAD_SUCCESS: 1>#

property name#

property value#

class omni.ext.ExtensionManager#

add_path( self: omni.ext._extensions.ExtensionManager, path: str, type: omni.ext._extensions.ExtensionPathType = <ExtensionPathType.COLLECTION: 0>, ) → None#

add_path_protocol_provider( self: omni.ext._extensions.ExtensionManager, scheme: str, on_add_path_fn: Callable[[str], str], on_remove_path_fn: Callable[[str], None], ) → bool#

Add new path protocol provider, scheme must be unique false returned otherwise.

Parameters:

scheme (str) – Scheme name.
fn (Callable[[str], str]) – The callback to be called when new search path is added for this scheme.

add_registry_provider( self: omni.ext._extensions.ExtensionManager, name: str, provider: omni::ext::IRegistryProvider, ) → bool#

Add registry provider to be used for remote extension registry.

Parameters:

name (str) – Provider unique name.
provider (IRegistryProvider) – Provider.

fetch_all_extension_packages( self: omni.ext._extensions.ExtensionManager, ) → tuple#

fetch_extension_packages( self: omni.ext._extensions.ExtensionManager, arg0: str, ) → tuple#

fetch_extension_summaries( self: omni.ext._extensions.ExtensionManager, ) → tuple#

fetch_extension_versions( self: omni.ext._extensions.ExtensionManager, arg0: str, ) → tuple#

get_change_event_stream( self: omni.ext._extensions.ExtensionManager, ) → carb.events._events.IEventStream#

get_enabled_extension_id( self: omni.ext._extensions.ExtensionManager, ext_name: str, ) → str#

get_enabled_extension_module_names()#: Get all python modules of enabled extensions

get_extension_dict( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → carb.dictionary._dictionary.Item#

get_extension_id_by_module(module: str) → str#: Get enabled extension id that contains this python module.

get_extension_packages( self: omni.ext._extensions.ExtensionManager, ) → tuple#

get_extension_path( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → str#

get_extension_path_by_module(module: str) → str#: Get enabled extension path that contains this python module.

get_extensions( self: omni.ext._extensions.ExtensionManager, ) → tuple#

get_folders( self: omni.ext._extensions.ExtensionManager, ) → tuple#

Get folders monitored for python extensions.

Returns (List[Dict]):: List of folders. Each folder is dict with “path” and “builtin” key.

get_hooks( self: omni.ext._extensions.ExtensionManager, ) → omni::ext::IExtensionManagerHooks#

get_registry_extension_dict( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → carb.dictionary._dictionary.Item#

get_registry_extension_packages( self: omni.ext._extensions.ExtensionManager, ) → tuple#

get_registry_extensions( self: omni.ext._extensions.ExtensionManager, ) → tuple#

get_registry_providers( self: omni.ext._extensions.ExtensionManager, ) → tuple#

is_extension_enabled( self: omni.ext._extensions.ExtensionManager, ext_name: str, ) → bool#

pack_extension( ext_id: str, output_folder: str, ) → str#

Pack extension into archive.

Supports both single file extensions (kit files) and folders.

Parameters:

ext_id (str) – Local extension id.
output_folder – Folder to output archive into.

Returns:

Path to archived extension.

Return type:

str

process_and_apply_all_changes( self: omni.ext._extensions.ExtensionManager, ) → None#

publish_extension( self: omni.ext._extensions.ExtensionManager, ext_id: str, provider_name: str = '', allow_overwrite: bool = False, ) → bool#

pull_extension( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → bool#

pull_extension_async( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → None#

refresh_registry( self: omni.ext._extensions.ExtensionManager, ) → None#

remove_path( self: omni.ext._extensions.ExtensionManager, path: str, ) → None#

remove_path_protocol_provider( self: omni.ext._extensions.ExtensionManager, scheme: str, ) → None#

remove_registry_provider( self: omni.ext._extensions.ExtensionManager, name: str, ) → None#

Remove registry provider.

Parameters:: name (str) – Provider unique name.

set_extension_enabled( self: omni.ext._extensions.ExtensionManager, extension_id: str, enabled: bool, ) → None#

Toggle extension enable/disable.

Parameters:

extension_id (str) – Extension id. Full python module name, returned by get_extensions.
enabled (bool) – Enable/disable toggle.

set_extension_enabled_immediate( self: omni.ext._extensions.ExtensionManager, extension_id: str, enabled: bool, ) → bool#

Toggle extension enable/disable immediately.

Parameters:

extension_id (str) – Extension id. Full python module name, returned by get_extensions.
enabled (bool) – Enable/disable toggle.

Returns (bool):: Failure or success.

set_extensions_excluded( self: omni.ext._extensions.ExtensionManager, exts: List[str], ) → None#

Set extensions to exclude on following solver/startup routines. They persist until next call to this function.

Parameters:: extensions (List[str]) – List Extension id with or without versions.

solve_extensions( self: omni.ext._extensions.ExtensionManager, exts: List[str], add_enabled: bool = False, return_only_disabled: bool = False, ) → tuple#

Run extension dependencies solver on the input.

Input is a list of extension, they can be names, full id, partial versions like ommi.foo-2.

Parameters:

exts (List[str]) – List of extensions.
add_enabled (bool) – Automatically add already enabled extension to the input (to take into account)
return_only_disabled (bool) – If true exclude from the result extensions that are currently already enabled

Returns(Tuple[bool, List[str], str]):: Tuple of result, list of extensions (solution) and error message.

subscribe_to_extension_enable( self: omni.ext._extensions.ExtensionManager, on_enable_fn: Callable[[str], None], on_disable_fn: Callable[[str], None] = None, ext_name: str = '', hook_name: str = '', ) → Tuple[omni::ext::IHookHolder, omni::ext::IHookHolder]#

Call callback if extension is enabled and hook in extension system to wait for extension to be enabled again (after reload for instance) and disabled.

Example:

def on_ext_enabled(ext_id: str):
    print("enabled:" + ext_id)

def on_ext_disabled(ext_id: str):
    print("disabled:" + ext_id)

manager = omni.kit.app.get_app().get_extension_manager()
self.hooks = manager.subscribe_to_extension_enable(on_ext_enabled, on_ext_disabled, ext_name="omni.kit.window.console", hook_name="la la la")
# Notice that we stored subscription holder somewhere (in self for instance) to hold it.

Parameters:

on_enable_fn (Callable[[str]]) – The callback to be called when extension is enabled. It accepts extension id.
on_disable_fn (Callable[[str]], optional) – The callback to be called when extension is disabled. It accepts extension id.
ext_name (str, optional) – Extension name to look for. Hook is only called for extensions with matching name. Can be empty.
hook_name (str) – Hook name for debugging and logging.

Returns:

Pair of hook holders.

sync_registry( self: omni.ext._extensions.ExtensionManager, ) → bool#

uninstall_extension( self: omni.ext._extensions.ExtensionManager, ext_id: str, ) → bool#

unpublish_extension( self: omni.ext._extensions.ExtensionManager, ext_id: str, provider_name: str = '', ) → bool#

class omni.ext.ExtensionPathType#

Index Refresh States.

Members:

COLLECTION

COLLECTION_USER

COLLECTION_CACHE

DIRECT_PATH

EXT_1_FOLDER

COLLECTION = <ExtensionPathType.COLLECTION: 0>#

COLLECTION_CACHE = <ExtensionPathType.COLLECTION_CACHE: 4>#

COLLECTION_USER = <ExtensionPathType.COLLECTION_USER: 3>#

DIRECT_PATH = <ExtensionPathType.DIRECT_PATH: 1>#

EXT_1_FOLDER = <ExtensionPathType.EXT_1_FOLDER: 2>#

property name#

property value#

class omni.ext.ExtensionStateChangeType#

Members:

BEFORE_EXTENSION_ENABLE

AFTER_EXTENSION_ENABLE

BEFORE_EXTENSION_DISABLE

AFTER_EXTENSION_DISABLE

COUNT

AFTER_EXTENSION_DISABLE = <ExtensionStateChangeType.AFTER_EXTENSION_DISABLE: 3>#

AFTER_EXTENSION_ENABLE = <ExtensionStateChangeType.AFTER_EXTENSION_ENABLE: 1>#

BEFORE_EXTENSION_DISABLE = <ExtensionStateChangeType.BEFORE_EXTENSION_DISABLE: 2>#

BEFORE_EXTENSION_ENABLE = <ExtensionStateChangeType.BEFORE_EXTENSION_ENABLE: 0>#

COUNT = <ExtensionStateChangeType.COUNT: 4>#

property name#

property value#

class omni.ext.ICppExt#

shutdown(self: omni.ext._extensions.ICppExt) → None#

startup(self: omni.ext._extensions.ICppExt, arg0: str) → None#

class omni.ext.IExt#

class omni.ext.IExtensionManagerHooks#

create_extension_state_change_hook( self: omni.ext._extensions.IExtensionManagerHooks, fn: Callable[[str, omni.ext._extensions.ExtensionStateChangeType], None], type: omni.ext._extensions.ExtensionStateChangeType, ext_name: str = '', ext_dict_path: str = '', order: int = 0, hook_name: str = '', ) → omni.ext._extensions.IHookHolder#

Create extension state change hook.

Hook is valid while returned hook holder object is alive.

Parameters:

fn (Callable[[str, ExtensionStateChangeType]]) – The callback to be called on extension state change event. It accepts extension id and type of hook event.
type (ExtensionStateChangeType) – Extension state change moment to hook into.
ext_name (str, optional) – Extension name to look for. Hook is only called for extensions with matching name. Can be empty.
ext_dict_path (str, optional) – Extension dictionary path to look for. Hook is only called if it is present.
order (int, optional) – Hook call order (if there are multiple).
hook_name (str) – Hook name for debugging and logging.

Returns:

The hook holder.

class omni.ext.IExtensions#

create_extension_manager( self: omni.ext._extensions.IExtensions, arg0: carb.events._events.IEventStream, ) → omni.ext._extensions.ExtensionManager#

class omni.ext.IHookHolder#: Hook holder.

class omni.ext.IRegistryProvider#

omni.ext.acquire_ext_interface( plugin_name: str = None, library_path: str = None, ) → omni.ext._extensions.ICppExt#

omni.ext.acquire_extensions_interface( plugin_name: str = None, library_path: str = None, ) → omni.ext._extensions.IExtensions#

omni.ext.create_link(link_path: str, target_path: str, target_is_dir=True)#

Creates a symbolic link from ‘link_path’ to ‘target_path’

Parameters:

link_path – Absolute or relative path to link to create
target_path – Absolute or relative path to target; if relative then it is relative to ‘link_path’
target_is_dir – This boolean is only used on Windows to specify if the target is a directory or file.

omni.ext.destroy_link(link_folder_path)#

Destroys an existing file system link

Parameters:: link_folder_path – Path to linked folder to destroy.

omni.ext.get_all_sys_paths() → Iterator[str]#

Get all sys.path, both handled by the fast importer and regular left in sys.path.

Use that function instead of sys.path if fast importer is enabled (it is enabled by default). Note, that this function is a generator and doesn’t return a ready list.

omni.ext.get_dangling_references( who, frame_depth_to_ignore: int = 0, full_details: bool = False, ) → str#

Returns a string containing debugging information about dangling references on an object.

Different levels of detail will be provided based on the environment variable “GC_DEBUG”, provided by the two methods _get_dangling_references_shallow() and _get_dangling_references_deep().

This is a tool that is useful for tracking down Python object leaks when an extension is unloaded and reloaded, to ensure you are properly cleaning up when the extension shuts down. You can insert calls to this in various locations of your code where you suspect objects are left dangling.

That code is open for improvement to figure out more info on who holds an object. For instance It can go recursively up the tree to get more info on who holds what.

Parameters:

who – Object to check for referrers in the garbage collector
frame_depth_to_ignore – Number of frames above this one deemed irrelevant to the leak detector e.g. the caller, a wrapper function invoking the caller, etc.
full_details – If True then add the very verbose _builtins, _globals, and _locals information

Returns:

String containing a multi-line description of the references that remain on the object

omni.ext.get_extension_name(ext_id: str) → str#: Convert ‘omni.foo-tag-1.2.3’ to ‘omni.foo-tag’

omni.ext.get_extensions_interface() → IExtensions#: Returns cached omni.ext.IExtensions interface

omni.ext.get_fast_importer_sys_paths()#

Get all sys.path handled by the fast importer.

If fast importer is enabled it takes a lot of paths from sys.path. This function returns all of them. If you need all sys.path as if fast importer is disabled, use get_all_sys_paths().

omni.ext.is_link(path: str) → bool#

omni.ext.pack_extension( package_id: str, ext_path: str, output_folder: str, ) → str#

Pack extension into archive.

Supports both single file extensions (kit files) and folders.

Parameters:

package_id (str) – Extension package id. Resulting archive will be [package_id].zip
ext_path (str) – Path to extension folder or file.
output_folder – Folder to output archive into.

Returns:

Path to archived extension.

Return type:

str

omni.ext.release_ext_interface(arg0: omni.ext._extensions.ICppExt) → None#

omni.ext.unpack_extension( archive_path: str, output_folder: str, ext_id: str | None = None, archive_subdir: str | None = None, skip_security_checks=True, )#

Unpack extenson making it ready to use if output folder is in extension search paths.

Supports both single file extensions (kit files) and folders.

Parameters:

archive_path (str) – Path to archive.
output_folder – Folder to unpack extension into.
ext_id (str) – Extension id to use to build folder name. By default acrhive filename is used.
archive_subdir (str) – Subdir in the archive to unpack, by default archive root is used.
skip_security_checks (bool) – if registry of this extension is trusted we skip extra security checks.

omni.kit.app#

This module contains bindings to C++ omni::kit::IApp interface, core C++ part of Omniverse Kit.

All the function are in omni.kit.IApp class, to get it use get_app_interface method, which caches acquire interface call:

>>> import omni.kit.app
>>> a = omni.kit.app.get_app()

class omni.kit.app.IApp#

delay_app_ready( self: omni.kit.app._app.IApp, requester_name: str, ) → None#

get_app_environment(self: omni.kit.app._app.IApp) → str#: Name of the environment we are running in. (/app/environment/name setting, e.g.: teamcity, launcher, etm, default)

get_app_filename(self: omni.kit.app._app.IApp) → str#: App filename. Name of a kit file

get_app_name(self: omni.kit.app._app.IApp) → str#: App name. It is app/name setting if defined, otherwise same as filename

get_app_version(self: omni.kit.app._app.IApp) → str#: App version. Version in kit file or kit version

get_app_version_short(self: omni.kit.app._app.IApp) → str#: Short app version, currently major.minor, e.g. 2021.3

get_build_version(self: omni.kit.app._app.IApp) → str#

get_extension_manager( self: omni.kit.app._app.IApp, ) → omni.ext._extensions.ExtensionManager#

get_kernel_version(self: omni.kit.app._app.IApp) → str#: Full kit kernel version, e.g. 103.5+release.7032.aac30830.tc.windows-x86_64.release

get_kit_version(self: omni.kit.app._app.IApp) → str#: Full kit version, e.g. 103.5+release.7032.aac30830.tc.windows-x86_64.release

get_kit_version_hash(self: omni.kit.app._app.IApp) → str#: Git hash of kit build, 8 letters, e.g. aac30830

get_kit_version_short(self: omni.kit.app._app.IApp) → str#: Short kit version, currently major.minor. e.g. 103.5

get_log_event_stream( self: omni.kit.app._app.IApp, ) → carb.events._events.IEventStream#: Log event stream.

get_message_bus_event_stream( self: omni.kit.app._app.IApp, runloop_name: str = 'main', ) → carb.events._events.IEventStream#

get_platform_info(self: omni.kit.app._app.IApp) → dict#

get_post_update_event_stream( self: omni.kit.app._app.IApp, runloop_name: str = 'main', ) → carb.events._events.IEventStream#

get_pre_update_event_stream( self: omni.kit.app._app.IApp, runloop_name: str = 'main', ) → carb.events._events.IEventStream#

get_python_scripting( self: omni.kit.app._app.IApp, ) → omni::kit::IAppScripting#

get_shutdown_event_stream( self: omni.kit.app._app.IApp, ) → carb.events._events.IEventStream#

get_startup_event_stream( self: omni.kit.app._app.IApp, ) → carb.events._events.IEventStream#

get_time_since_start_ms(self: omni.kit.app._app.IApp) → float#

get_time_since_start_s(self: omni.kit.app._app.IApp) → float#

get_update_event_stream( self: omni.kit.app._app.IApp, runloop_name: str = 'main', ) → carb.events._events.IEventStream#

get_update_number(self: omni.kit.app._app.IApp) → int#

is_app_external(self: omni.kit.app._app.IApp) → bool#: Is external (public) configuration

is_app_ready(self: omni.kit.app._app.IApp) → bool#

is_debug_build(self: omni.kit.app._app.IApp) → bool#

is_running(self: omni.kit.app._app.IApp) → bool#

async next_update_async() → float#: Wait for next update of Omniverse Kit. Return delta time in seconds

post_quit( self: omni.kit.app._app.IApp, return_code: int = 0, ) → None#

post_uncancellable_quit( self: omni.kit.app._app.IApp, return_code: int = 0, ) → None#

async post_update_async() → float#

async pre_update_async() → float#: Wait for next update of Omniverse Kit. Return delta time in seconds

print_and_log(self: omni.kit.app._app.IApp, message: str) → None#

replay_log_messages( self: omni.kit.app._app.IApp, arg0: carb._carb.logging.Logger, ) → None#: Replays recorded log messages for the specified target.

report_alive(self: omni.kit.app._app.IApp) → None#

restart( self: omni.kit.app._app.IApp, args: List[str] = [], overwrite_args: bool = False, uncancellable: bool = False, ) → None#

run( self: omni.kit.app._app.IApp, app_name: str, app_path: str, argv: List[str] = [], ) → int#

shutdown(self: omni.kit.app._app.IApp) → int#

startup( self: omni.kit.app._app.IApp, app_name: str, app_path: str, argv: List[str] = [], ) → None#

toggle_log_message_recording( self: omni.kit.app._app.IApp, arg0: bool, ) → None#: Toggles log message recording.

try_cancel_shutdown( self: omni.kit.app._app.IApp, reason: str = '', ) → bool#

update(self: omni.kit.app._app.IApp) → None#

class omni.kit.app.IAppScripting#

add_search_script_folder( self: omni.kit.app._app.IAppScripting, path: str, ) → bool#

execute_file( self: omni.kit.app._app.IAppScripting, path: str, args: List[str], ) → bool#

execute_string( self: omni.kit.app._app.IAppScripting, str: str, source_file: str = '', execute_as_file: bool = '', ) → bool#

get_event_stream( self: omni.kit.app._app.IAppScripting, ) → carb.events._events.IEventStream#

remove_search_script_folder( self: omni.kit.app._app.IAppScripting, path: str, ) → bool#

class omni.kit.app.SettingChangeSubscription(path: str, on_change: Callable)#: Setting change subscription wrapper to make it scoped (auto unsubscribe on del)

omni.kit.app.acquire_app_interface( plugin_name: str = None, library_path: str = None, ) → omni.kit.app._app.IApp#

omni.kit.app.crash() → None#

omni.kit.app.deprecated(message='')#: Decorator which can be used to mark functions or classes as deprecated. It will result in warn log when the function is used or a class is instantiated.

omni.kit.app.get_app() → IApp#: Returns cached omni.kit.app.IApp interface. (shorthand)

omni.kit.app.get_app_interface() → IApp#: Returns cached omni.kit.app.IApp interface

omni.kit.app.log_deprecation(message: str)#: Log deprecation message.

omni.kit.app.send_telemetry_event( event_type: str, duration: float = 0, data1: str = '', data2: str = '', value1: float = 0.0, value2: float = 0.0, )#

Send generic telemetry event.

It is a helper, so that just one liner: omni.kit.app.send_telemetry_event can be used anywhere instead of checking for telemetry being enabled at each call site.

If telemetry is not enabled this function does nothing.

Parameters:

event_type (str) – A string describing the event that occurred. There is no restriction on the content or formatting of this value. This should neither be nullptr nor an empty string.
duration (float) – A generic duration value that can be optionally included with the event.
data1 (str) – A string data value to be sent with the event. The interpretation of this string depends on event_type.
data2 (str) – A string data value to be sent with the event. The interpretation of this string depends on event_type.
value1 (float) – A float data value to be sent with the event. The interpretation of this string depends on event_type.
value2 (float) – A float data value to be sent with the event. The interpretation of this string depends on event_type.

omni.log#

class omni.log.ChannelUpdateReason#

Reason for a channel update notification.

Members:

CHANNEL_ADDED : A channel was added.

CHANNEL_REMOVED : A channel was removed.

LEVEL_UPDATED : The channel’s level or level behavior was updated.

ENABLED_UPDATED : The channel’s enabled flag or enabled behavior was updated.

DESCRIPTION_UPDATED : The channel’s description was updated.

CHANNEL_ADDED = <ChannelUpdateReason.CHANNEL_ADDED: 0>#

CHANNEL_REMOVED = <ChannelUpdateReason.CHANNEL_REMOVED: 1>#

DESCRIPTION_UPDATED = <ChannelUpdateReason.DESCRIPTION_UPDATED: 4>#

ENABLED_UPDATED = <ChannelUpdateReason.ENABLED_UPDATED: 3>#

LEVEL_UPDATED = <ChannelUpdateReason.LEVEL_UPDATED: 2>#

property name#

property value#

class omni.log.ILog#

Multi-channel logging interface which can write logs to multiple consumers.

See the @rstref{Omniverse Logging Guide <carb_logging>} to better understand how logging works from both the user’s and developer’s point-of-view.

In practice, use of this interface is hidden to the user. Most logging occurs via the following macros:

@ref OMNI_LOG_VERBOSE
@ref OMNI_LOG_INFO
@ref OMNI_LOG_WARN
@ref OMNI_LOG_ERROR
@ref OMNI_LOG_FATAL

The macros above internally call @ref omniGetLogWithoutAcquire(), which returns an @ref omni::log::ILog pointer. See @ref omniGetLogWithoutAcquire() for details on how to control which @ref omni::log::ILog pointer is returned.

The logging interface defines two concepts: log channels and log consumers.

Log channels are identified by a string and represent the idea of a logging “channel”. Each channel has a:

Enabled/Disabled flag (see @ref omni::log::ILog::setChannelEnabled()).
Log level at which messages should be ignored (see @ref omni::log::ILog::setChannelLevel()).

Each message logged is associated with a single log channel.

Each time a message is logged, the channel’s settings are checked to see if the message should be filtered out. If the message is not filtered, the logging interface formats the message and passes it to each log message consumer.

Log consumers (e.g. @ref omni::log::ILogMessageConsumer) are attached to the logging system via @ref omni::log::ILog::addMessageConsumer(). Along with the formatted message, log consumers are passed a bevvy of additional information, such as filename, line number, channel name, message level, etc. The consumer may choose to perform additional filtering at this point. Eventually, it is up to the log consumer to “log” the message to its backing store (e.g. stdout).

The @ref omni::log::ILog interface itself has a global enable/disabled flag and log level. Each channel can choose to respect the global flags (via @ref omni::log::SettingBehavior::eInherit) or override the global flags with their own (via @ref omni::log::SettingBehavior::eOverride).

With these settings, user have fine-grain control over which messages are filtered and where messages are logged.

See @ref OMNI_LOG_ADD_CHANNEL() for information on creating and registering log channels.

In order to support rich user experiences, the logging system also allows consumers to be notified of internal state changes such as a channel being added, the logging level changing, etc. See @ref omni::log::ILog::addChannelUpdateConsumer() for details.

add_channel_update_consumer(*args, **kwargs)#

Overloaded function.

add_channel_update_consumer(self: omni.log._log.ILog, arg0: Callable[[omni.log._log.ILog, omni.str._str.IReadOnlyCString, omni.log._log.ChannelUpdateReason], None]) -> omni::log::ILogChannelUpdateConsumer

Adds the given channel updated consumer to the internal list of update consumers.

Each time the state of the log changes, each update consumer is notified.

A consumer can be registered a single time with a given @ref omni::log::ILog instance but can be registered with multiple @ref omni::log::ILog instances.

Each message may be sent to registered consumers in parallel.

It is safe to access @ref omni::log::ILog from the callback.

@thread_safety This method is thread safe.

add_channel_update_consumer(self: omni.log._log.ILog, arg0: omni::log::ILogChannelUpdateConsumer) -> None

add_message_consumer( self: omni.log._log.ILog, arg0: Callable[[str, omni.log._log.Level, str, str, str, int, str, int, int, int], None], ) → omni::log::ILogMessageConsumer#

Adds the given log consumer to the internal list of log consumers.

Each message is associated with a single log channel. When a message is logged by a log channel, the message is checked to see if it should be filtered. If not, it is given to the logging system (@ref omni::log::ILog) which eventually sends the message to each registered @ref omni::log::ILogMessageConsumer.

A consumer can be registered a single time with a given @ref omni::log::ILog instance but can be registered with multiple @ref omni::log::ILog instances.

Each message may be sent to registered consumers in parallel.

Logging a message from a consumer callback will lead to undefined behavior.

Calling @ref omni::log::ILog::addMessageConsumer() from @ref omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.

@thread_safety This method is thread safe.

property enabled#

flush(self: omni.log._log._ILog) → None#

Flush all queued messages to message consumers.

If asynchronous logging is enabled (see @ref omni::log::ILog::setAsync), blocks until all pending messages have been delivered to message consumers.

@thread_safety This method is thread safe.

get_channel_description( self: omni.log._log.ILog, arg0: str, ) → tuple#

get_channel_enabled(self: omni.log._log.ILog, name: str) → tuple#

Returns the given channel’s logging enabled state and override behavior.

All parameters must be non-nullptr.

If the given channel is not found, an @ref omni::core::kResultNotFound is returned.

Return @ref omni::core::kResultSuccess upon success, a failure code otherwise.

@thread_safety This method is thread safe.

get_channel_level(self: omni.log._log.ILog, name: str) → tuple#

Returns the given channel’s logging level and override behavior.

All parameters must be non-nullptr.

If the given channel is not found, an @ref omni::core::kResultNotFound is returned.

@return Returns @ref omni::core::kResultSuccess upon success, a failure code otherwise.

@thread_safety This method is thread safe.

get_channel_names(self: omni.log._log.ILog) → tuple#

is_async(self: omni.log._log._ILog) → bool#

Returns true if asynchronous logging is enabled.

@thread_safety This method is thread safe.

is_logging_at_level( self: omni.log._log.ILog, name: str, level: omni.log._log.Level, ) → bool#

Given a channel and a verbosity level, returns true if the channel is actively logging at the given level.

Using the OMNI_LOG_* macros is preferred over this method, as those macros use a much more efficient method to filter messages. However, the mechanics utilized by OMNI_LOG_* are not viable when binding to languages such as Python, thus this method’s existence.

@thread_safety This method is thread safe.

property level#

remove_channel_update_consumer( self: omni.log._log.ILog, consumer: omni::log::ILogChannelUpdateConsumer, ) → None#

Removes the given consumer from the internal consumer list.

This method silently accepts nullptr.

This method silently accepts consumers that have not been registered with this object.

Calling @ref omni::log::ILog::removeChannelUpdateConsumer() from @ref omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.

@thread_safety This method is thread safe.

remove_message_consumer( self: omni.log._log.ILog, consumer: omni::log::ILogMessageConsumer, ) → None#

Removes the given consumer from the internal consumer list.

This method silently accepts nullptr.

This method silently accepts consumers that have not been registered with this object.

Calling @ref omni::log::ILog::removeMessageConsumer() from omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.

@thread_safety This method is thread safe.

set_async(self: omni.log._log._ILog, log_async: bool) → bool#

Instructs the logging system to deliver all log messages to the logging backends asynchronously.

This causes @ref omni::log::ILog::log() calls to be buffered so that @ref omni::log::ILog::log() may return as quickly as possible. A background thread then issues these buffered log messages to the registered Logger backend objects.

@thread_safety This method is thread safe.

@returns Returns the state of asynchronous logging before this method was called.

set_channel_description( self: omni.log._log.ILog, name: str, description: str, ) → None#

Sets a channel’s description. If the channel does not exists, it is created.

The given channel @p name and @p description must not be nullptr.

The memory pointed to by @p description is copied by this method.

If the channel already has a description, it is replaced.

@thread_safety This method is thread safe.

set_channel_enabled( self: omni.log._log.ILog, name: str, is_enabled: bool, behavior: omni.log._log.SettingBehavior, ) → None#

Sets the given channel’s enabled/disabled flag.

If the channel has not yet been registered with @ref omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.

@thread_safety This method is thread safe.

set_channel_level( self: omni.log._log.ILog, name: str, level: omni.log._log.Level, behavior: omni.log._log.SettingBehavior, ) → None#

Sets the given channel’s log level.

If the channel has not yet been registered with @ref omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.

@thread_safety This method is thread safe.

class omni.log.ILogChannelFilter#

Read-only object to encapsulate a channel filter’s pattern and effects.

A channel filter is a pattern matcher. If a channel’s name matches the pattern, the filter can set both the channel’s enabled flag and/or level.

property filter#

get_enabled( self: omni.log._log.ILogChannelFilter, ) → tuple#

Returns the desired enabled state for this filter.

All parameters must not be nullptr.

If isUsed is false after calling this method, isEnabled and behavior should not be used.

This method is thread safe.

get_level( self: omni.log._log.ILogChannelFilter, ) → tuple#

Returns the desired level for this filter.

All parameters must not be nullptr.

If isUsed is false after calling this method, level and behavior should not be used.

This method is thread safe.

is_match( self: omni.log._log.ILogChannelFilter, channel: str, ) → bool#

Given a channel name, returns if the channel name matches the filter’s pattern.

The matching algorithm used is implementation specific (e.g. regex, glob, etc).

This method is thread safe.

class omni.log.ILogChannelUpdateConsumer#

Consumes (listens for) state change to one or more @ref omni::log::ILog objects.

Add this object to an omni::log::ILog via @ref omni::log::ILog::addChannelUpdateConsumer().

on_channel_update( self: omni.log._log.ILogChannelUpdateConsumer, log: omni.log._log.ILog, name: omni.str._str.IReadOnlyCString, reason: omni.log._log.ChannelUpdateReason, ) → None#

Called when an attached @ref omni::log::ILog’s state changes.

Accessing the given omni::log::ILog from this method is safe.

If @p name is nullptr, the change happened to the global log (i.e. not to a specific channel).

@thread_safety

This method must be thread safe as the attached ILogs may send messages to this object in parallel.

Updates may come out-of-order and may be spurious.

class omni.log.ILogMessageConsumer#

Consumes (listens for) log messages.

@ref omni::log::ILogMessageConsumer is usually associated with an @ref omni::log::ILog instance. Add a consumer to an @ref omni::log::ILog object with @ref omni::log::ILog::addMessageConsumer().

on_message( self: omni.log._log.ILogMessageConsumer, channel: str, level: omni.log._log.Level, module_name: str, file_name: str, function_name: str, line_number: int, msg: str, pid: int, tid: int, timestamp: int, ) → None#

Receives a log message.

Logging a message from this method results in undefined behavior.

Accessing the owning @ref omni::log::ILog from this method will lead to undefined behavior.

The memory pointed to by the provided pointers will remain valid only during the duration of this call.

@thread_safety This method must be thread safe as the attached @ref omni::log::ILog may send messages to this object in parallel.

class omni.log.Level#

Severity of a message.

Members:

VERBOSE : Verbose level, for detailed diagnostics messages.

INFO : Info level, this is for informational messages.

WARN : Warning level, this is for warning messages.

ERROR : Error level, this is for error messages.

FATAL : Fatal level, this is for messages on unrecoverable errors.

DISABLED : Internal flag used to disable logging.

DISABLED = <Level.DISABLED: 3>#

ERROR = <Level.ERROR: 1>#

FATAL = <Level.FATAL: 2>#

INFO = <Level.INFO: -1>#

VERBOSE = <Level.VERBOSE: -2>#

WARN = <Level.WARN: 0>#

property name#

property value#

class omni.log.SettingBehavior#

Defines if a log channel’s setting should be respected or if the global logging system’s settings should be used.

Members:

INHERIT : Use the log system’s setting.

OVERRIDE : Use the setting defined by the log channel.

INHERIT = <SettingBehavior.INHERIT: 0>#

OVERRIDE = <SettingBehavior.OVERRIDE: 1>#

property name#

property value#

omni.log.error(msg: str, channel=None, origin_stack_depth=1)#: Logs an error.

omni.log.fatal(msg: str, channel=None, origin_stack_depth=1)#: Logs a fatal error. This function only logs. This function does _not_ terminate the process.

omni.log.get_log() → omni.log._log.ILog#

omni.log.info(msg: str, channel=None, origin_stack_depth=1)#: Logs an informational message.

omni.log.log( level: Level, msg: str, channel=None, origin_stack_depth=1, )#

Logs a message at the given level.

origin_stack_depth – Describes how many stack frames to move up to grab information about the origin of the log message (filename, line number, etc). A valid of 1 (the default) means use the stack information from the function that called this function. A value greater than 1 can be used when wrapping this function.

omni.log.verbose(msg: str, channel=None, origin_stack_depth=1)#: Logs a verbose message.

omni.log.warn(msg: str, channel=None, origin_stack_depth=1)#: Logs a warning.

omni.platforminfo#

class omni.platforminfo.Architecture#

Names for the processor architecture for the system.

Members:

UNKNOWN : /< The architecture is unknown or could not be determined.

X86_64 : /< Intel X86 64 bit.

AARCH64 : /< ARM 64-bit.

AARCH64 = <Architecture.AARCH64: 2>#

UNKNOWN = <Architecture.UNKNOWN: 0>#

X86_64 = <Architecture.X86_64: 1>#

property name#

property value#

class omni.platforminfo.CompositorInfo#

property name#: /< The name of the active compositor. This must not be modified.

property release_version#: /< The release version number of the active compositor.

property vendor#: /< The vendor of the active compositor. This must not be modified.

class omni.platforminfo.CpuFeature#

CPU feature names. Each feature name is used with ICpuInfo::isFeatureSupported() to: determine if the requested CPU running on the calling system supports the feature. These feature flags mostly focus on the availability of specific instructions sets on the host CPU.

Members:

X86_SSE : /< Intel SSE instructions are supported.

X86_SSE2 : /< Intel SSE2 instructions are supported.

X86_SSE3 : /< Intel SSE3 instructions are supported.

X86_SSSE3 : /< Intel supplementary SSE3 instructions are supported.

X86_FMA : /< Fused multiply-add SIMD operations are supported.

X86_SSE41 : /< Intel SSE4.1 instructions are supported.

X86_SSE42 : /< Intel SSE4.2 instructions are supported.

X86_AVX : /< Intel AVX instructions are supported.

X86_F16C : /< 16-bit floating point conversion instructions are supported.

X86_POPCNT : /< Instruction for counting set bits are supported.

X86_TSC : /< The RDTSC instruction is supported.

X86_MMX : /< Intel MMX instructions are supported.

X86_AVX2 : /< Intel AVX2 instructions are supported.

X86_AVX512_F : /< The AVX-512 foundation instructions are supported.

X86_AVX512_DQ : /< The AVX-512 double and quad word instructions are supported.

X86_AVX512_IFMA : /< The AVX-512 integer fused multiply-add instructions are supported.

X86_AVX512_PF : /< The AVX-512 prefetch instructions are supported.

X86_AVX512_ER : /< The AVX-512 exponential and reciprocal instructions are supported.

X86_AVX512_CD : /< The AVX-512 conflict detection instructions are supported.

X86_AVX512_BW : /< The AVX-512 byte and word instructions are supported.

X86_AVX512_VL : /< The AVX-512 vector length extensions instructions are supported.

X86_AVX512__VBMI : /< The AVX-512 vector byte manipulation instructions are supported.

X86_AVX512__VBMI2 : /< The AVX-512 vector byte manipulation 2 instructions are supported.

X86_AVX512__VNNI : /< The AVX-512 vector neural network instructions are supported.

X86_AVX512__BITALG : /< The AVX-512 bit algorithms instructions are supported.

X86_AVX512__VPOPCNTDQ : /< The AVX-512 vector population count instructions are supported.

X86_AVX512_4_VNNIW : /< The AVX-512 word vector neural network instructions are supported.

X86_AVX512_4FMAPS : /< The AVX-512 packed single fused multiply-add instructions are supported.

X86_AVX512__VP2INTERSECT : /< The AVX-512 vector pair intersection instructions are supported.

X86_AVX_VNNI : /< The AVX VEX-encoded versions of the neural network instructions are supported.

X86_AVX512__BF16 : /< The AVX-512 16-bit floating point vector NN instructions are supported.

AMD3_D_NOW : /< The AMD 3DNow! instruction set is supported.

AMD3_D_NOW_EXT : /< The AMD 3DNow! extensions instruction set is supported.

AMD_MMX_EXT : /< The AMD MMX extensions instruction set is supported.

ARM_ASIMD : /< The advanced SIMD instructions are supported.

ARM_NEON : /< The ARM Neon instruction set is supported.

ARM_ATOMICS : /< The ARMv8 atomic instructions are supported.

ARM_SHA : /< The SHA1 and SHA2 instruction sets are supported.

ARM_CRYPTO : /< The ARM AES instructions are supported.

ARM_CRC32 : /< The ARM CRC32 instructions are supported.

FEATURE_COUNT : @}

AMD3_D_NOW = <CpuFeature.AMD3_D_NOW: 31>#

AMD3_D_NOW_EXT = <CpuFeature.AMD3_D_NOW_EXT: 32>#

AMD_MMX_EXT = <CpuFeature.AMD_MMX_EXT: 33>#

ARM_ASIMD = <CpuFeature.ARM_ASIMD: 34>#

ARM_ATOMICS = <CpuFeature.ARM_ATOMICS: 36>#

ARM_CRC32 = <CpuFeature.ARM_CRC32: 39>#

ARM_CRYPTO = <CpuFeature.ARM_CRYPTO: 38>#

ARM_NEON = <CpuFeature.ARM_NEON: 35>#

ARM_SHA = <CpuFeature.ARM_SHA: 37>#

FEATURE_COUNT = <CpuFeature.FEATURE_COUNT: 40>#

X86_AVX = <CpuFeature.X86_AVX: 7>#

X86_AVX2 = <CpuFeature.X86_AVX2: 12>#

X86_AVX512_4FMAPS = <CpuFeature.X86_AVX512_4FMAPS: 27>#

X86_AVX512_4_VNNIW = <CpuFeature.X86_AVX512_4_VNNIW: 26>#

X86_AVX512_BW = <CpuFeature.X86_AVX512_BW: 19>#

X86_AVX512_CD = <CpuFeature.X86_AVX512_CD: 18>#

X86_AVX512_DQ = <CpuFeature.X86_AVX512_DQ: 14>#

X86_AVX512_ER = <CpuFeature.X86_AVX512_ER: 17>#

X86_AVX512_F = <CpuFeature.X86_AVX512_F: 13>#

X86_AVX512_IFMA = <CpuFeature.X86_AVX512_IFMA: 15>#

X86_AVX512_PF = <CpuFeature.X86_AVX512_PF: 16>#

X86_AVX512_VL = <CpuFeature.X86_AVX512_VL: 20>#

X86_AVX512__BF16 = <CpuFeature.X86_AVX512__BF16: 30>#

X86_AVX512__BITALG = <CpuFeature.X86_AVX512__BITALG: 24>#

X86_AVX512__VBMI = <CpuFeature.X86_AVX512__VBMI: 21>#

X86_AVX512__VBMI2 = <CpuFeature.X86_AVX512__VBMI2: 22>#

X86_AVX512__VNNI = <CpuFeature.X86_AVX512__VNNI: 23>#

X86_AVX512__VP2INTERSECT = <CpuFeature.X86_AVX512__VP2INTERSECT: 28>#

X86_AVX512__VPOPCNTDQ = <CpuFeature.X86_AVX512__VPOPCNTDQ: 25>#

X86_AVX_VNNI = <CpuFeature.X86_AVX_VNNI: 29>#

X86_F16C = <CpuFeature.X86_F16C: 8>#

X86_FMA = <CpuFeature.X86_FMA: 4>#

X86_MMX = <CpuFeature.X86_MMX: 11>#

X86_POPCNT = <CpuFeature.X86_POPCNT: 9>#

X86_SSE = <CpuFeature.X86_SSE: 0>#

X86_SSE2 = <CpuFeature.X86_SSE2: 1>#

X86_SSE3 = <CpuFeature.X86_SSE3: 2>#

X86_SSE41 = <CpuFeature.X86_SSE41: 5>#

X86_SSE42 = <CpuFeature.X86_SSE42: 6>#

X86_SSSE3 = <CpuFeature.X86_SSSE3: 3>#

X86_TSC = <CpuFeature.X86_TSC: 10>#

property name#

property value#

class omni.platforminfo.DisplayFlags#

Base type for the display information flags. These flags all start with fDisplayFlag.

Members:

PRIMARY : Flag that indicates that the display is the primary one in the system.

PRIMARY = <DisplayFlags.PRIMARY: 1>#

property name#

property value#

class omni.platforminfo.DisplayInfo#

property adapter_id#: The system specific identifier of the graphics adapter device. This is suitable for using with other platform specific APIs that accept a graphics adapter name.

property adapter_name#: The name of the graphics adapter the display is connected to. Typically this is the name of the GPU or other graphics device that the display is connected to. This name should be suitable for display to a user.

property current#: The current display mode in use on the display.

property display_id#: The system specific identifier of the display device. This is suitable for using with other platform specific APIs that accept a display device name.

property display_name#: The name of the display device. This typically maps to a monitor, laptop screen, or other pixel display device. This name should be suitable for display to a user.

property flags#: Flags to indicate additional information about this display.

property origin#: The coordinates of the origin of this display device on the desktop’s virtual screen. In situations where there is only a single display, this will always be (0, 0). It will be in non-mirrored multi-display setups that this can be used to determine how each display’s viewport is positioned relative to each other.

class omni.platforminfo.ICGroupCpuInfo#

@brief Interface to collect CPU information directly from Linux’s root level control group.

Interface to collect Linux control group (“cgroup”) information about the CPU(s) installed in the calling system. This can provide some basic information about the CPU core count, scheduling quotas, and active CPU sets. The values reported from this interface will reflect any CPU resource limitations imposed on the system by an external source. For example, the available CPUs could be limited in a container, a VM, or by an OS level per-user quota.

This interface is intended to be used to directly retrieve the cgroup information about the CPU if set. If a particular value is not set (ie: logical core count, CPU set, scheduling quota), the corresponding function will fail allowing the caller to fall back to another information source such as the bare metal values.

This interface is available on Windows for convenience, but all functions will simply fail when called. This makes it easier to call into the interface without needing additional nullptr checks.

@note The CPU information will only be collected once on loading this plugin and cached: for later retrieval. If the CPU core allocation changes dynamically while the calling process is still running (and therefore the container is still running), this change will not be reflected in the returned values.

@note This interface supports cgroup versions 1 and 2 on Linux.

property core_usage_quota#

property cpu_set_logical_core_count#

get_core_set_list( self: omni.platforminfo._platforminfo.ICGroupCpuInfo, cores: sequence, ) → tuple#

Retrieves the set of CPU cores available to the calling process.

@param[out] cores Receives the list of core indices for all CPU cores available to
the calling process. If no CPU set has been defined that limits access to specific cores, this will simply return 0. This may be nullptr if the list of core indices is not needed. In this case the total required size of the buffer will be returned if a CPU set is defined.

@param[in] maxCores The maximum number of CPU core indices that can fit in @p cores.
This may be 0 to retrieve the required size of the buffer.

@returns The total number of CPU core indices written to the buffer @p cores if a
CPU set has been defined in the cgroup and @p cores is non-nullptr. If @p cores is nullptr the required size of the buffer in indices is returned. If the buffer is not large enough to hold the full CPU set indices, as many indices as will fit are written to the buffer and the required size of the buffer is returned. If no CPU set has been defined, 0 is returned.

@remarks This retrieves the indices of the logical cores in the active CPU set.
Depending on the cgroup version that is supported in the system, this value can come from either one of the following files in this priority order:

/sys/fs/cgroup/cpuset.cpus.effective (v2)

/sys/fs/cgroup/cpuset.cpus (v2)

/sys/fs/cgroup/cpuset/cpuset.effective_cpus (v1)

/sys/fs/cgroup/cpuset/cpuset.cpus (v1)

@thread_safety This call is thread safe.

class omni.platforminfo.ICGroupMemoryInfo#

@brief Interface to collect memory information directly from Linux’s root control group.

Interface to collect and retrieve information about cgroup limited memory installed in the system. The values reported from this interface will reflect any memory limitations imposed on the system by an external source. For example, the system memory could be limited in a container, a VM, or by an OS level per-user quota.

This interface is intended to be used to directly retrieve the cgroup information about the system memory if set. If a particular value is not set in the cgroup (ie: memory limit, swap limit, etc), the corresponding function will fail allowing the caller to fall back to another information source such as the bare metal values.

This interface is available on Windows for convenience, but all functions will simply fail when called. This makes it easier to call into the interface without needing additional nullptr checks.

@note This interface supports cgroup versions 1 and 2 on Linux.

get_available_page_file_memory( self: omni.platforminfo._platforminfo.ICGroupMemoryInfo, ) → tuple#

Retrieves the available allowed page file space in the system.

@param[out] bytes Receives the number of bytes of page file space that is currently
available for use by the operating system if a swap space limit is set in the cgroup. Receives 0 if no swap space limit is set in the cgroup. This may not be nullptr.

@returns true if a swap space limit is set and the available swap space memory amount
was retrieved successfully. Returns false if no swap space limit is set.

@remarks This retrieves the available page file space in a limited system resource
situation. Depending on the cgroup version that is supported in the system, this value either comes from the file /sys/fs/cgroup/memory.swap.current (v2) or the swap field of /sys/fs/cgroup/memory/memory.stat.

@thread_safety This call is thread safe. However, two consecutive or concurrent calls
are unlikely to return the same value.

get_available_physical_memory( self: omni.platforminfo._platforminfo.ICGroupMemoryInfo, ) → tuple#

Retrieves the available allowed physical memory in the system.

@param[out] bytes Receives the number of bytes of physical memory that is currently
available and accessible for use by the operating system. Note that this is not a measure of how much memory is available to the calling process, but rather for the entire system. This value will reflect the amount of memory available for the given cgroup memory limit. Receives 0 if no memory limit is set. This may not be nullptr.

@returns true if a memory limit is set and the available memory amount was retrieved
successfully. Returns false if no memory limit is set.

@remarks This retrieves the available RAM that the calling process is allowed to access
in a limited resource situation. Depending on the cgroup version that is supported in the system, this value either comes from the file /sys/fs/cgroup/memory.current (v2) or /sys/fs/cgroup/memory/memory.usage_in_bytes (v1).

@thread_safety This call is thread safe. However, two consecutive or concurrent calls
are unlikely to return the same value.

get_total_page_file_memory( self: omni.platforminfo._platforminfo.ICGroupMemoryInfo, ) → tuple#

Retrieves the total accessible page file space in the system.

@param[out] bytes Receives the number of bytes of page file space in the system. The
value will not change during the lifetime of the calling process and can be safely cached. Receives 0 if no swap space limit is set in the cgroup. This may not be nullptr.

@returns true if a swap space limit has been set in the cgroup and is successfully
retrieved. Returns false if no swap space limit is set in the cgroup.

@remarks This retrieves the total accessible page file space in a limited system
resource situation. This value is only available on systems that support cgroup v2 from the file /sys/fs/cgroup/memory.swap.max. Swap space limitations are not supported on cgroup v1 as a lone value. It is only available as a combined swap plus memory value.

@thread_safety This call is thread safe.

get_total_physical_memory( self: omni.platforminfo._platforminfo.ICGroupMemoryInfo, ) → tuple#

Retrieves the maximum RAM accessible by the calling process.

@param[out] bytes Receives the number of bytes of physical RAM installed in the system
and allowed for use by the calling process. This value will not change during the lifetime of the calling process and can be safely cached. Receives 0 if no memory limit is set. This may not be nullptr.

@returns true if a memory limit is set in the cgroup and that value is retrieved.
Returns false if no memory limit is set in the cgroup. In this case, the bare metal physical memory limit should be used instead.

@remarks This retrieves the maximum RAM that the calling process is allowed to access
in a limited resource situation. Depending on the cgroup version that is supported in the system, this value either comes from the file /sys/fs/cgroup/memory.max (v2) or /sys/fs/cgroup/memory/memory.limit_in_bytes (v1).

@thread_safety This call is thread safe.

class omni.platforminfo.ICpuInfo#

Interface to collect information about the CPUs installed in the calling system. This can provide some basic information about the CPU(s) and get access to features that are supported by them. This is intended to retrieve the bare metal CPU information, not any that are limited by a container, VM, or OS level resource limitation.

property cpu_package_count#

get_identifier( self: omni.platforminfo._platforminfo._ICpuInfo, cpu_index: int, ) → str#

Retrieves the identifier of a CPU in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the identifier
for. This should be less than the return value of ICpuInfo::getCpuPackageCount().

@returns The identifier string of the requested CPU package. This string should be
suitable for display to the user. This will contain information about the processor family, vendor, and architecture.

@thread_safety This call is thread safe.

get_pretty_name( self: omni.platforminfo._platforminfo._ICpuInfo, cpu_index: int, ) → str#

Retrieves the friendly name of a CPU in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the name
for. This should be less than the return value of ICpuInfo::getCpuPackageCount().

@returns The friendly name of the requested CPU package. This string should be suitable
for display to the user. This will contain a rough outline of the processor model and architecture. It may or may not contain the clock speed.

@thread_safety This call is thread safe.

get_processor_mask( self: omni.platforminfo._platforminfo._ICpuInfo, cpu_index: int, ) → int#

Retrieves a bit mask for the processor cores in a CPU package in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the identifier
for. This should be less than the return value of ICpuInfo::getCpuPackageCount().

@returns A mask identifying which CPU cores the given CPU covers. A set bit indicates
a core that belongs to the given CPU. A 0 bit indicates either a core from another package or a non-existent core. This may also be 0 if more than 64 cores are present in the system or they are out of range of a single 64-bit value.

@note The mask may be 0 if out of range of 64 bits.

@thread_safety This call is thread safe.

get_vendor( self: omni.platforminfo._platforminfo._ICpuInfo, cpu_index: int, ) → str#

Retrieves the vendor string for a CPU package in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the vendor
for. This should be less than the return value of ICpuInfo::getCpuPackageCount().

@returns The name of the vendor as reported by the CPU itself. This may be something
along the lines of “GenuineIntel” or “AuthenticAMD” for x86_64 architectures, or the name of the CPU implementer for ARM architectures.

@thread_safety This call is thread safe.

is_feature_supported( self: omni.platforminfo._platforminfo._ICpuInfo, feature: omni.platforminfo._platforminfo.CpuFeature, ) → bool#

Checks if a requested feature is supported by the CPU(s) in the system.

@returns true if the requested feature is supported. Returns false otherwise.

@remarks See @ref omni::platforminfo::CpuFeature for more information on the features
that can be queried.

@thread_safety This call is thread safe.

property logical_cores_per_package#

property physical_cores_per_package#

property total_logical_core_count#

property total_physical_core_count#

class omni.platforminfo.IDisplayInfo#

Interface to collect and retrieve information about displays attached to the system. Each display is a viewport onto the desktop’s virtual screen space and has an origin and size. Most displays are capable of switching between several modes. A mode is a combination of a viewport resolution (width, height, and color depth), and refresh rate. Display info may be collected using this interface, but it does not handle making changes to the current mode for any given display.

property display_count#

get_display_info( self: omni.platforminfo._platforminfo.IDisplayInfo, display_index: int, ) → tuple#

Retrieves information about a single connected display.

@param[in] displayIndex The zero based index of the display to retrieve the information
for. This call will fail if the index is out of the range of the number of connected displays, thus it is not necessary to IDisplayInfo::getDisplayCount() to enumerate display information in a counted loop.

@param[out] infoOut Receives the information for the requested display. This may
not be nullptr. This returned information may change at any time due to user action and should therefore not be cached.

@returns true if the information for the requested display is successfully retrieved.
Returns false if the @p displayIndex index was out of the range of connected display devices or the information could not be retrieved for any reason.

@thread_safety This call is thread safe.

get_mode_count( self: omni.platforminfo._platforminfo.IDisplayInfo, display: omni.platforminfo._platforminfo.DisplayInfo, ) → int#

Retrieves the total number of display modes for a given display.

@param[in] display The display to retrieve the mode count for. This may not be
nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().

@returns The total number of display modes supported by the requested display. Returns
0 if the mode count information could not be retrieved. A connected valid display will always support at least one mode.

@thread_safety This call is thread safe.

get_mode_info( self: omni.platforminfo._platforminfo.IDisplayInfo, display: omni.platforminfo._platforminfo.DisplayInfo, mode_index: int, ) → tuple#

Retrieves the information for a single display mode for a given display.

@param[in] display The display to retrieve the mode count for. This may not be
nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().

@param[in] modeIndex The zero based index of the mode to retrieve for the given
display. This may also be @ref omni::platforminfo::kModeIndexCurrent to retrieve the information for the given display’s current mode. This call will simply fail if this index is out of range of the number of modes supported by the given display, thus it is not necessary to call omni::platforminfo::IDisplayInfo::getModeCount() to use in a counted loop.

@param[out] infoOut Receives the information for the requested mode of the given
display. This may not be nullptr.

@returns true if the information for the requested mode is successfully retrieved.
Returns false if the given index was out of range of the number of modes supported by the given display or the mode’s information could not be retrieved for any reason.

@thread_safety This call is thread safe.

get_total_display_size( self: omni.platforminfo._platforminfo.IDisplayInfo, ) → tuple#

Retrieves the total virtual screen size that all connected displays cover.

@param[out] origin Receives the coordinates of the origin of the rectangle that the
virtual screen covers. This may be nullptr if the origin point is not needed.

@param[out] size Receives the width and height of the rectangle that the virtual
screen covers. This may be nullptr if the size is not needed.

@returns true if either the origin, size, or both origin and size of the virtual
screen are retrieved successfully. Returns false if the size of the virtual screen could not be retrieved or both @p origin and @p size are nullptr.

@remarks This retrieves the total virtual screen size for the system. This is the
union of the rectangles that all connected displays cover. Note that this will also include any empty space between or around displays that is not covered by another display.

@thread_safety This call is thread safe.

class omni.platforminfo.ILimitedCpuInfo#

Interface to collect information about the CPUs installed in the calling system. This can provide some basic information about the CPU(s) and get access to features that are supported by them. The values reported from this interface will reflect any CPU resource limitations imposed on the system by an external source. For example, the available CPUs could be limited in a container, a VM, or by an OS level per-user quota.

This interface has mostly the same set of functions that the @ref omni::platforminfo::ICpuInfo interface does. The only difference is in its behavior - it will retrieve the CPU info _available_ to the calling process under a resource limiting system such as Docker or a CM instead of the bare metal values. If no limits are set on the container or VM, this will fall back to reporting the same bare metal values as @ref omni::platforminfo::ICpuInfo instead.

Some of the functions of @ref omni::platforminfo::ICpuInfo have been removed here since they do not make sense in a resource limiting situation. Some new functions have also been added to retrieve more specific CPU core limiting information.

@note The CPU information will only be collected once on loading this plugin and cached: for later retrieval. If the CPU core allocation changes dynamically while the calling process is still running (and therefore the container is still running), this change will not be reflected in the returned values.

property core_usage_quota#

property cpu_package_count#

get_core_set_list( self: omni.platforminfo._platforminfo.ILimitedCpuInfo, cores: sequence, ) → tuple#

Retrieves the set of CPU cores available to the calling process.

@param[out] cores Receives the list of core indices for all CPU cores available to
the calling process. If no CPU set has been defined that limits access to specific cores, this will simply return a list of all core indices on the bare metal CPU. This may not be nullptr. This buffer should be large enough to hold as many core indices as omni::platforminfo::ILimitedCpuInfo::getTotalLogicalCoreCount().

@param[in] maxCores The maximum number of CPU core indices that can fit in @p cores.

@returns true if the CPU core list is successfully returned. Returns false if
the @p cores buffer is too small to hold the full core indices list.

@thread_safety This call is thread safe.

get_identifier( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → str#

Retrieves the identifier of a CPU in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the identifier
for. This should be less than the return value of @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns The identifier string of the requested CPU package. This string should be
suitable for display to the user. This will contain information about the processor family, vendor, and architecture.

@note This CPU identifier string will still be retrieved from the CPU itself even if
access to CPU cores has been limited.

@thread_safety This call is thread safe.

get_logical_core_count_for_package( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → int#

Retrieves the logical CPU core count for a specific CPU package.

@param[in] cpuIndex The CPU package to retrieve the logical core count for. This
must be less than the value returned from @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns The total number of logical CPU cores on the requested CPU package. This will
never be 0. Any CPU packages that do not have cores assigned to them in the limited CPU resource case will be removed.

@thread_safety This call is thread safe.

get_physical_core_count_for_package( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → int#

Retrieves the physical CPU core count for a specific CPU package.

@param[in] cpuIndex The CPU package to retrieve the physical core count for. This
must be less than the value returned from @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns The estimated number of physical CPU cores on the requested CPU package. Note
that this is only an estimate since logical cores may be assigned asymmetrically in a container or VM. This is estimated using the bare metal physical-vs-logical core multiplier. It is most accurate to only use the logical core count when making decisions based off of the CPU core count.

@thread_safety This call is thread safe.

get_pretty_name( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → str#

Retrieves the friendly name of a CPU in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the name
for. This should be less than the return value of @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns The friendly name of the requested CPU package. This string should be suitable
for display to the user. This will contain a rough outline of the processor model and architecture. It may or may not contain the clock speed.

@note This CPU pretty name string will still be retrieved from the CPU itself even if
access to CPU cores has been limited.

@thread_safety This call is thread safe.

get_processor_mask( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → int#

Retrieves a bit mask for the processor cores in a CPU package in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the identifier
for. This should be less than the return value of @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns A mask identifying which CPU cores the given CPU covers. A set bit indicates
a core that belongs to the given CPU. A 0 bit indicates either a core from another package or a non-existent core. This may also be 0 if more than 64 cores are present in the system or they are out of range of a single 64-bit value.

@note The mask may be 0 if out of range of 64 bits.

@thread_safety This call is thread safe.

get_vendor( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, cpu_index: int, ) → str#

Retrieves the vendor string for a CPU package in the system.

@param[in] cpuIndex The zero based index of the CPU package to retrieve the vendor
for. This should be less than the return value of @ref omni::platforminfo::ILimitedCpuInfo::getCpuPackageCount().

@returns The name of the vendor as reported by the CPU itself. This may be something
along the lines of “GenuineIntel” or “AuthenticAMD” for x86_64 architectures, or the name of the CPU implementer for ARM architectures.

@note This CPU vendor string will still be retrieved from the CPU itself even if
access to CPU cores has been limited.

@thread_safety This call is thread safe.

is_feature_supported( self: omni.platforminfo._platforminfo._ILimitedCpuInfo, feature: omni.platforminfo._platforminfo.CpuFeature, ) → bool#

Checks if a requested feature is supported by the CPU(s) in the system.

@returns true if the requested feature is supported. Returns false otherwise.

@remarks See @ref omni::platforminfo::CpuFeature for more information on the features
that can be queried.

@thread_safety This call is thread safe.

property total_logical_core_count#

property total_physical_core_count#

class omni.platforminfo.ILimitedMemoryInfo#

Interface to collect and retrieve information about memory installed in the system. The values reported from this interface will reflect any memory limitations imposed on the system by an external source. For example, the system memory could be limited in a container, a VM, or by an OS level per-user quota.

This interface has the same set of functions that the @ref omni::platforminfo::IMemoryInfo interface does. The only difference is in its behavior - it will retrieve the memory values _available_ to the calling process under a resource limiting system such as Docker or a VM instead of the bare metal values. If no limits are set on the container or VM, this will fall back to reporting the same bare metal values as @ref omni::platforminfo::IMemoryInfo instead.

property available_page_file_memory#

property available_physical_memory#

property process_memory_usage#

property process_peak_memory_usage#

property total_page_file_memory#

property total_physical_memory#

class omni.platforminfo.IMemoryInfo#

Interface to collect and retrieve information about memory installed in the system. The values retrieved by this interface will reflect the total bare metal RAM available to the system, not any values that have been limited by OS level user quotas, containers, or VMs.

property available_page_file_memory#

property available_physical_memory#

property process_memory_usage#

property process_peak_memory_usage#

property total_page_file_memory#

property total_physical_memory#

class omni.platforminfo.IOsInfo#

Interface to collect and retrieve information about the operating system.

property architecture#

property code_name#

property compositor_info#

property distro_name#

property kernel_version#

property name#

property os#

property os_version#

property pretty_name#

class omni.platforminfo.IOsInfo2#

Extended interface to collect and retrieve more information about the operating system. This inherits from omni::platforminfo::IOsInfo and also provides all of its functionality.

property compatibility_mode_enabled#

get_machine_id( self: omni.platforminfo._platforminfo.IOsInfo2, extraData: str = None, flags: int = 0, ) → int#

Generates a repeatable machine ID with the current algorithm.

@param[in] extraData A caller provided null terminated string containing extra
information to include in the machine ID calculation. This can be used to make the generated machine ID more unique to the specific user or device. This may be nullptr if no extra information is needed.

@param[in] flags Flags to control how the machine ID is generated. In most
cases this should only pass in the @ref omni::platforminfo::fMachineIdFlagDefault flag. Note that using different flags will also change the value of the generated machine ID.

@returns A 64-bit integer representing the generated machine ID on success. Returns
0 if the requested version number is out of range of what the current version of the plugin can provide.

@see See omni::platforminfo::IOsInfo2::getMachineIdEx() for more information on the
usage of this function.

get_machine_id_ex( self: omni.platforminfo._platforminfo.IOsInfo2, extra_data: str, flags: int, version: int, ) → int#

Generates a repeatable machine ID.

@param[in] extraData A caller provided null terminated string containing extra
information to include in the machine ID calculation. This can be used to make the generated machine ID more unique to the specific user or device. This may be nullptr if no extra information is needed.

@param[in] flags Flags to control how the machine ID is generated. In most
cases this should only pass in the @ref omni::platforminfo::fMachineIdFlagDefault flag. Note that using different flags will also change the value of the generated machine ID.

@param[in] version The version of the machine ID to generate. This should be
@ref omni::platforminfo::kMachineIdCurrent in most cases. Though note that the generated machine ID may change from one version to the next. If this version number is out of the range of what is supported by the current plugin version, a machine ID of 0 will be returned instead.

@returns A 64-bit integer representing the generated machine ID on success. Returns
0 if the requested version number is out of range of what the current version of the plugin can provide.

@remarks This generates a machine ID value that can be used to describe or identify
the calling machine in an anonymous way. The returned machine ID will be a hash of the names of various hardware components and OS version information, plus the provided extra data. Even if the current user’s personal information is included in this hash through the @p extraData string, it will not be recoverable since both the remainder and order of the information included in the hash will be implementation specific and not fully known externally.

@note When generated without using any of the flags that make the machine ID unique,
the generated value can be safely cached for a given @p extraData value since future attempts to generate it with the same value will yield the same result.

@note The value of the generated machine ID will change from one run to the next on
the same machine if certain hardware is changed (ie: new CPU, memory upgrade, new graphics adapter, etc) or the OS is upgraded. This is expected behavior.

class omni.platforminfo.MachineIdFlags#

Base type for the flags used in omni::platforminfo::IOsInfo2::getMachineId().

Members:

DEFAULT : Flag to indicate that the default functionality should be used when generating the machine ID value.

MAKE_UNIQUE : Flag to indicate that the generated machine ID should be created with the addition of extra information that changes frequently. Multiple calls to generate a machine ID using this flag will produce different results even within the same process. Note that this will only be guaranteed to be statistically unique on the same machine. There is a very slim probability that a machine ID generated on another machine with identical components and OS and using this flag could generate the same value.

SESSION_UNIQUE : Flag to indicate that the generated machine ID should be created with the addition of extra information that stays the same for the duration of the calling process. Machine IDs generated by another process even on the same machine will generate a different value. Note that if the omni.platforminfo plugin is unloaded and loaded again in the same process, machine IDs generated with this flag will differ from previous ones. There is a very slim probability that a machine ID generated on another machine with identical components and OS and using this flag could generate the same value.

DEFAULT = <MachineIdFlags.DEFAULT: 0>#

MAKE_UNIQUE = <MachineIdFlags.MAKE_UNIQUE: 1>#

SESSION_UNIQUE = <MachineIdFlags.SESSION_UNIQUE: 2>#

property name#

property value#

class omni.platforminfo.MachineIdVersion#

Base type for the version numbers for the way that machine IDs are generated.

Members:

BASE_VERSION : Name for the first version of the machine ID generation algorithm. Future versions may change the algorithm and therefore generate different machine IDs.

CURRENT : Placeholder name for the current version of the machine ID generation algorithm supported by this implementation of this plugin.

BASE_VERSION = <MachineIdVersion.BASE_VERSION: 1>#

CURRENT = <MachineIdVersion.BASE_VERSION: 1>#

property name#

property value#

class omni.platforminfo.ModeFlags#

Base type for the display mode information flags. These flags all start with fModeFlag.

Members:

INTERLACED : Flag to indicate that the screen mode is interlaced.

STRETCHED : Flag to indicate that this mode will be stretched.

CENTERED : Flag to indicate that this mode will be centered on the display.

CENTERED = <ModeFlags.CENTERED: 4>#

INTERLACED = <ModeFlags.INTERLACED: 1>#

STRETCHED = <ModeFlags.STRETCHED: 2>#

property name#

property value#

class omni.platforminfo.ModeIndex#

Base type for a display mode index.

Members:

CURRENT : Special mode index value to get the information for a display’s current mode.

CURRENT = <ModeIndex.CURRENT: 18446744073709551615>#

property name#

property value#

class omni.platforminfo.ModeInfo#

property bits_per_pixel#: /< Pixel bit depth. Many modern systems will only report 32 bits.

property flags#: /< Flags describing the state of the mode.

property orientation#: /< The orientation of the mode.

property refresh_rate#: /< The refresh rate of the display in Hertz or zero if not applicable.

property size#: /< Horizontal (x) and vertical (y) size of the screen in pixels.

class omni.platforminfo.Orientation#

Possible display orientation names.

These indicate how the screen is rotated from its native default orientation. The rotation angle is considered in a clockwise direction.

Members:

DEFAULT : /< The natural display orientation for the display.

90 : /< The image is rotated 90 degrees clockwise.

180 : /< The image is rotated 180 degrees clockwise.

270 : /< The image is rotated 270 degrees clockwise.

180 = <Orientation.180: 2>#

270 = <Orientation.270: 3>#

90 = <Orientation.90: 1>#

DEFAULT = <Orientation.DEFAULT: 0>#

property name#

property value#

class omni.platforminfo.Os#

Names for the supported operating systems.

Members:

UNKNOWN : /< The OS is unknown or could not be determined.

WINDOWS : /< Microsoft Windows.

LINUX : /< Any flavor of Linux.

MAC_OS : /< Mac OS.

LINUX = <Os.LINUX: 2>#

MAC_OS = <Os.MAC_OS: 3>#

UNKNOWN = <Os.UNKNOWN: 0>#

WINDOWS = <Os.WINDOWS: 1>#

property name#

property value#

class omni.platforminfo.OsVersion#

property build_number#: /< OS specific build number.

property major#: /< Major version.

property minor#: /< Minor version.

omni.schema#

class omni.schema.Schema_omni_processlifetime_1_1#

event_sendEvent( self: omni.schema._processlifetime.Schema_omni_processlifetime_1_1, event: str, context: str, ) → None#

heartbeat_sendEvent( self: omni.schema._processlifetime.Schema_omni_processlifetime_1_1, ) → None#

omni.str#

class omni.str.IReadOnlyCString#

Reference counted read-only C-style (i.e. null-terminated) string.

property buffer#

omni.structuredlog#

class omni.structuredlog.IStructuredLogControl#

Structured log state control interface. This allows for some control over the processing of events and log files for the structured log system. The structured log system’s event queue can be temporarily stopped if needed or the output log for a schema may be closed. Each of these operations is only temporary as the event queue will be restarted and the log file opened when the next event is queued with @ref omni::structuredlog::IStructuredLog::allocEvent().

This interface object can be acquired either by requesting it from the type factory or by casting an @ref omni::structuredlog::IStructuredLog object to this type.

close_log( self: omni.structuredlog._structuredlog._IStructuredLogControl, event: int, ) → None#

Closes one or more schema’s persistently open log file(s).

@param[in] event The ID of the event to close the log for. This may also be
@ref omni::structuredlog::kAllSchemas to close all log file for the process. The log file for the schema that the given event belongs to will be closed.

@returns No return value.

@remarks This closes the persistently open log file(s) for one or more schemas. This
operation will effectively be ignored for schemas that were not registered using the @ref omni::structuredlog::fSchemaFlagKeepLogOpen schema flag since those schemas will not leave their logs open. The named log files will only remain closed until the next attempt to write an event message to it. It is the responsibility of the host app to ensure no events are written to the effected log file(s) for the duration that the log needs to remain closed.

@note This call itself is thread safe. However the log file may be reopened if a
pending event is processed in the event queue or a new event is sent while the calling thread expects the log to remain closed. It is the caller’s responsibility to either stop the event queue, disable structured logging, or prevent other events from being sent while the log(s) need to remain closed.

stop( self: omni.structuredlog._structuredlog._IStructuredLogControl, ) → None#

Stop the structured log event consumer thread.

@returns No return value.

@remarks This stops the structured log event processing system. This will stop the
processing thread and flush all pending event messages to the log. The processing system will be restarted when the next @ref omni::structuredlog::IStructuredLog::allocEvent() call is made to attempt to send a new message. This call is useful if the structured log plugin needs to be unloaded. If the processing thread is left running, it will prevent the plugin from being unloaded (or even being attempted to be unloaded). This can also be used to temporarily disable the structured log system if its not needed or wanted. If the structured log system needs to be disabled completely, a call to @ref omni::structuredlog::IStructuredLog::setEnabled() using the @ref omni::structuredlog::fEnableFlagAll flag should be made before stopping the event queue.

@thread_safety This call is thread safe.

class omni.structuredlog.IStructuredLogControl2#

Interface for the second version of the IStructuredLogControl interface. This interface exposes more functions to control the behavior of the structured logging system. This object can be retrieved directly or by casting the main IStructuredLog interface to this type using omni::core::ObjectPtr::as<>().

emit_process_lifetime_exit_event( self: omni.structuredlog._structuredlog.IStructuredLogControl2, reason: str, ) → None#

Immediately emits the process lifetime exit event for the process.

@param[in] reason The reason why the exit event is being emitted. This can be any text
that gives and indication for why an exit is occurring. This may not be nullptr and should not be an empty string.

@returns No return value.

@remarks This forces the process lifetime exit event to be emitted early for the process.
If this is called, it will pre-empt the normal attempt to emit it automatically when omni.structuredlog.plugin unloads. This can be used to provide a different reason message for the exit event or to explicitly emit the event in situations where omni.structuredlog.plugin cannot be properly unloaded (ie: another system leaks or hangs onto a reference to one of the objects from the library).

@note This should only ever be called when a process shutdown is iminent and cannot be
cancelled or avoided. If this is emitted earlier in the process than exit time, the analysis of the process’ duration could be incorrect.

@note Calling this will flush the structuredlog queue to ensure the event is flushed to disk
before the process exits.

class omni.structuredlog.IStructuredLogExtraFields#

Interface to manage extra CloudEvent fields to be included in each emitted message. This allows for fields to be added and removed as needed. It also allows existing registered fields to be enumerated at any given time. An extra field is a key/value pair that is included at the top level of the JSON object for each message that follows. Only string values are allowed for each key.

set_value( self: omni.structuredlog._structuredlog.IStructuredLogExtraFields, field_name: str, value: str, flags: int, ) → bool#

Adds, modifies, or removes an extra field key/value pair.

@param[in] fieldName The name of the field to add, modify or remove. This may not be
nullptr or and empty string. The field name must only contain alphabetic, numeric, or underscore ASCII characters. Any characters outside these will cause the field to not be updated. Further, this may not be one of the reserved CloudEvent field names such as “specversion”, “data”, “time”, “source”, “session”, “dataschema”, “type”, or “subject”.

@param[in] value The new value to set for the requested extra field. This may be
nullptr to indicate that the named field should be removed. The value string may include any characters, but should be limited to a small number of characters (ideally less than 64 characters).

@param[in] flags Flags to control how the new value is added, modified, or removed.
Currently no flags are defined. This must be set to @ref omni::structuredlog::fExtraFieldFlagNone.

@returns true if the requested extra field is successfully added, modified, or removed.
Returns false if an invalid field name is given, or the operation could not be completed for any reason.

@remarks This adds, modifies, or removes a registered extra field and value. Any extra
fields that are registered at the time a message is emitted will be added to the message on output. At least for the first version of this interface it is expected that extra fields be largely static.

@thread_safety This call is thread safe.

class omni.structuredlog.IStructuredLogFromILog#

This interface controls the ability to send Carbonite and Omniverse logging through the structured log system. The output is equivalent to the standard logging output, except that it is in JSON, so it will be easier for programs to consume.

The default state of structured log logging is off, but it can be enabled by calling @ref omni::structuredlog::IStructuredLogFromILog::enableLogging() or setting /structuredLog/enableLogConsumer to true with ISettings.

disable_logging( self: omni.structuredlog._structuredlog._IStructuredLogFromILog, ) → None#

Disables the structured log logger.

@remarks After this is called, log messages will no longer be sent as structured log: events to the structured log system’s log file.

enable_logging( self: omni.structuredlog._structuredlog._IStructuredLogFromILog, ) → None#

Enable the structured log logger.

@remarks Enabling this will result in all Carbonite logging (e.g. CARB_LOG_*) and all: Omniverse logging (e.g. OMNI_LOG_*) going to the structured log log file. This may be useful if you want the logs to be consumed by some sort of log reader program. These log events will be sent to the default structured log system’s log file if there is one; they will otherwise go to a log file named “omni.structuredlog.logging-{version}”. These log events will not be sent to the collection servers.

property logging_event_id#

class omni.structuredlog.IStructuredLogFromILog2#

This extends the functionality of the @ref omni::structuredlog::IStructuredLogFromILog interface. This allows for the event flags of the log consumer event to be modified. This is an internal interface however and is not intended to be used externally.

property log_level#

set_logging_event_flags( self: omni.structuredlog._structuredlog._IStructuredLogFromILog2, set_flags: int, clear_flags: int, ) → bool#

Modifies the flags for the log consumer event.

@param[in] setFlags The set of flags to add to the log consumer event.

@param[in] clearFlags The set of flags to remove from the log consumer event. These
flags will be cleared before the flags from @p setFlags are added.

@returns true if the log consumer event’s flags were successfully modified. Returns
false if the log consumer event or schema is not present or did not get loaded.

class omni.structuredlog.IStructuredLogSettings#

Structured log settings interface. This allows a host app to modify some behavior of the structured log system for the process or to retrieve information about the current settings. These settings control features such as the event queue size, log rotation, event ID generation, the output log path, and the user ID. Most of the default settings should be sufficient for most apps with the exception of the user ID. For host apps that use at least one non-anonymized schema the only settings that must be set is the user ID.

This interface object can be acquired either by requesting it from the type factory or by casting an IStructuredLog object to this type.

enable_schemas_from_settings( self: omni.structuredlog._structuredlog._IStructuredLogSettings, ) → bool#

Checks app settings to see if any schemas or events should be disabled or enabled.

@returns true if the settings registry was successfully checked for enable or disable
states. Returns false if the ref carb::settings::ISettings or ref carb::dictionary::IDictionary plugins have not been loaded yet.

@remarks This checks the settings registry to determine if any schemas or events should
be disabled initially. The keys in the settings registry that will be looked at are under @ref omni::structuredlog::kSchemasStateListSetting, @ref omni::structuredlog::kEventsStateListSetting, @ref omni::structuredlog::kEventsStateArraySetting, and @ref omni::structuredlog::kSchemasStateArraySetting. Each of these parts of the settings registry expects the schema or event name to be specified in a different way. Once the settings have been loaded, they are cached internally and will be used as the initial state of any newly registered schemas or events. Any state changes to events or schemas after these settings are cached can still be done programmatically with @ref omni::structuredlog::IStructuredLog::setEnabled().

property event_id_mode#

property event_id_type#

property event_queue_size#

get_log_path_for_event( self: omni.structuredlog._structuredlog._IStructuredLogSettings, event_id: int, ) → str#

Retrieves the log path that a given event will be written to.

@param[in] eventId The ID of the event to retrieve the log path for. This must be the
same ID used when the event was registered. This may also be @ref omni::structuredlog::kDefaultLogPathEvent to retrieve the path for the default log.

@returns The name and path of the log file that the requested event would go to if it
were emitted with current settings.

@returns the name and path of the default log file if kDefaultLogPathEvent is used for
for the event ID.

@returns nullptr if the given event ID is unknown or kDefaultLogPathEvent was used
and no default log name has been set.

@thread_safety This call itself is thread safe. However, the returned string is only
valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

load_privacy_settings( self: omni.structuredlog._structuredlog._IStructuredLogSettings, ) → bool#

Attempts to load the privacy settings file.

@returns true if the privacy settings file was successfully loaded.

@returns false if the privacy settings file could not be loaded. This failure may be
caused by the file being missing, failing to open the file due to permissions, failing to allocate memory to read in the file, the file not being formatted correctly as a TOML file, or failing to merge the new values into the settings registry.

@remarks This will attempt to load the privacy settings file for the current user. Regardless
of whether the file is successfully loaded, appropriate defaults will always be set for each of the expected privacy settings (as long as the ISettings interface is available).

@note This expects that some other system has already found and attempted to load the
plugin that implements the ISettings interface.

property log_default_name#

property log_output_path#

property log_retention_count#

property log_size_limit#

property session_id#

set_event_id_mode( self: omni.structuredlog._structuredlog._IStructuredLogSettings, mode: omni::structuredlog::IdMode, type: omni::structuredlog::IdType, ) → None#

Sets the current event identifier mode and type.

@param[in] mode The new identifier mode to use. This will take effect on the next
event that is sent. The default is IdMode::eFastSequential.

@param[in] type The new identifier type to use. This will take effect on the next
event that is sent. The default is IdType::eUuid.

@returns No return value.

@thread_safety This call is thread safe.

property user_id#

class omni.structuredlog.IStructuredLogSettings2#

Interface for the second version of the IStructuredLogSettings interface. This interface exposes more settings to control the behaviour of the structured logging system. This object can be retrieved directly or by casting the main IStructuredLog interface to this type using omni::core::ObjectPtr::as<>().

property heartbeat_period#

property need_log_headers#

property output_flags#

set_output_flags( self: omni.structuredlog._structuredlog._IStructuredLogSettings2, flags_to_add: int, flags_to_remove: int, ) → None#

Sets or clears one or more output flags for structured logging.

@param[in] flagsToAdd A set of zero or more flag bits to set. These must be either
@ref omni::structuredlog::fOutputFlagNone or one or more of the @ref omni::structuredlog::OutputFlags flags.

@param[in] flagsToRemove A set of zero or more flag bits to cleared. These must be
either @ref omni::structuredlog::fOutputFlagNone or one or more of the @ref omni::structuredlog::OutputFlags flags.

@returns No return value.

@remarks This sets or clears flags that affect the output from the structured logging
system. These flags are all disabled by default. These flags will take effect the next time a message is emitted.

class omni.structuredlog.IdMode#

Names to control how the next event identifier is generated after each event message.

Members:

RANDOM : Each event identifier will be completely random. There will be no ordering relationship between any two events. This mode is useful when a sense of ordering is not needed but a very small probability of an event identifier collision is needed.

SEQUENTIAL : Each event identifier will be incremented by one from the previous one. When using a UUID identifier, this will increment the previous identifier by one starting from the rightmost value. When using a 64-bit identifier, this the previous identifier will just be incremented by one. This is useful when ordering is important and events may need to be sorted.

FAST_SEQUENTIAL : Each event identifier will be incremented by one from the previous one, but a faster method will be used. When using a UUID identifier, this will not produce an easily sortable set of identifiers, but it will be faster to produce versus the other methods. When using a 64-bit identifier, this mode is the same as @ref IdMode::eSequential and will produce an easily sortable set of identifiers. This is useful when event handling performance is the most important.

FAST_SEQUENTIAL = <IdMode.FAST_SEQUENTIAL: 2>#

RANDOM = <IdMode.RANDOM: 0>#

SEQUENTIAL = <IdMode.SEQUENTIAL: 1>#

property name#

property value#

class omni.structuredlog.IdType#

Names to control what type of event identifiers will be used for each message.

Members:

UUID : Generate a 128 bit UUID identifier. The probability of an identifier collision between two events will be especially small with this type, especially when using random identifiers. This however does have a small performance penalty to process these identifiers and could result in the event processing thread getting backed up if a large number of events are being pushed frequently.

UINT64 : Generate a 64-bit integer identifier. The probability of an identifier collision between two events will be higher but still small with this type, especially when using random identifiers. This identifier type is more performant and more easily sortable however. This identifier type is useful when event processing performance is most important.

UINT64 = <IdType.UINT64: 1>#

UUID = <IdType.UUID: 0>#

property name#

property value#

class omni.structuredlog.InvalidEventException#: An exception thrown when invalid data is passed to send_event()

class omni.structuredlog.InvalidSchemaException#: An exception thrown when an invalid schema is registered

class omni.structuredlog.StructuredLogEvent#

An opaque handle which identifies an individual telemetry event

property eventId#

property schema#

class omni.structuredlog.UniqueApp#

Helper class to manage the unique telemetry transmitter instance on the system. This can be used to ‘connect’ to the transmitter as a client which will prevent it from shutting down until your client has exited or disconnected.

Launching a transmitter through launchTransmitter() will create this guard already, so using a guard manually is only necessary in cases where that’s not being used, such as tests.

connect_client_process( self: omni.structuredlog._structuredlog.UniqueApp, ) → bool#

Notifies the unique app that a host app is running.

This lets the unique app know that the calling host app is still running. This is done by adding a shared lock reference to a marker file that the unique app can poll on periodically. The operating system will automatically remove the lock reference(s) for this call once the calling process exits (naturally or otherwise).

This call is not thread safe. It is the caller’s responsibility to ensure calls to it are protected. However, since it is meant to operate between processes, there may still be unavoidable race conditions that could arise.

Returns:

true if the unique app was successfully notified of the new running: host app. Returns false if the notification either couldn’t be sent or could not be completed.

disconnect_client_process( self: omni.structuredlog._structuredlog.UniqueApp, ) → None#

‘Disconnect’ the calling process from the exit guard.

This closes the calling process’s reference to the exit guard file. This will allow the exit guard for a host app process to be explicitly cleaned up before exit if needed.

This call is not thread safe. It is the caller’s responsibility to ensure calls to it are protected.

Returns:: None

omni.structuredlog.create_launch_guard() → omni.structuredlog._structuredlog.UniqueApp#

Create a guard with the standard name and path for the transmitter.

This guard is needed by all telemetry clients to let the transmitter know when all clients have shut down so it can exit as well.

Returns:: A UniqueApp guard that is used to let the transmitter know when it should exit on its own. Telemetry clients should use this to ‘connect’ to the transmitter (note that this does not require the transmitter to be running yet). See launchTransmitter() for an example usage.

omni.structuredlog.register_schema(schema: dict) → dict#

Register a schema with the structured logging system To be able to send events, you need to register a schema that specifies the data layout of your events.

Parameters:: schema – The dict specifying your message schema. This dict can be directly loaded from your JSON schema. If this schema isn’t a valid structured logging schema, this call will throw. Note that the ordering of the events in this dictionary, as well as the ordering of non-constant properties in the events is important. If you pass a schema in with events/properties rearranged, this call will throw an exception.
Returns:: This returns a dict, which contains a handle for each event that is used to call send_event(). The keys of this dictionary are the short names of each event. The value of each dictionary entry is opaque and should just be passed to send_event().

omni.structuredlog.send_event( eventInfo: omni::structuredlog::StructuredLogEvent, event: dict, ) → None#