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

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

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

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.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)

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.LoggerHandle

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

class carb.filesystem.DirectoryItemType

Members:

FILE

carb.audio

This module contains bindings for the IAudioPlayback interface. This is the low-level audio playback interface for Carbonite.

class carb.audio.AudioResult

Members:

OK

DEVICE_DISCONNECTED

DEVICE_LOST

DEVICE_NOT_OPEN

DEVICE_OPEN

OUT_OF_RANGE

TRY_AGAIN

OUT_OF_MEMORY

INVALID_PARAMETER

NOT_ALLOWED

NOT_FOUND

IO_ERROR

INVALID_FORMAT

NOT_SUPPORTED

DEVICE_DISCONNECTED = <AudioResult.DEVICE_DISCONNECTED: 1>

DEVICE_LOST = <AudioResult.DEVICE_LOST: 2>

DEVICE_NOT_OPEN = <AudioResult.DEVICE_NOT_OPEN: 3>

DEVICE_OPEN = <AudioResult.DEVICE_OPEN: 4>

INVALID_FORMAT = <AudioResult.INVALID_FORMAT: 12>

INVALID_PARAMETER = <AudioResult.INVALID_PARAMETER: 8>

IO_ERROR = <AudioResult.IO_ERROR: 11>

NOT_ALLOWED = <AudioResult.NOT_ALLOWED: 9>

NOT_FOUND = <AudioResult.NOT_FOUND: 10>

NOT_SUPPORTED = <AudioResult.NOT_SUPPORTED: 14>

OK = <AudioResult.OK: 0>

OUT_OF_MEMORY = <AudioResult.OUT_OF_MEMORY: 7>

OUT_OF_RANGE = <AudioResult.OUT_OF_RANGE: 5>

TRY_AGAIN = <AudioResult.TRY_AGAIN: 6>

property name

property value

class carb.audio.Context

The Context object for the audio system. Each individual Context represents an instance of the IAudioPlayback interface, as well as an individual connection to the system audio mixer/device. Only a small number of these can be opened for a given process.

get_caps(self: carb.audio.Context) → carb.audio.ContextCaps

retrieves the current capabilities and settings for a context object.

This retrieves the current capabilities and settings for a context object. Some of these settings may change depending on whether the context has opened an output device or not.

Parameters: arguments. (No) –
Returns: the context’s current capabilities and settings. This includes the speaker mode, speaker positions, maximum bus count, and information about the output device that is opened (if any).

get_parameters(self: carb.audio.Context, paramsToGet: int) → carb.audio.ContextParams

Retrieves one or more parameters for a context.

This retrieves the current values of one or more of a context’s parameters. Only the parameter values listed in paramsToGet flags will be guaranteed to be valid upon return.

Parameters: ParamsToGet – Flags indicating which parameter values need to be retrieved. This should be a combination of the CONTEXT_PARAM_* bitflags.
Returns: The requested parameters in a ContextParams struct. Everything else is default-initialized.

play_sound(self: carb.audio.Context, sound: carb::audio::PythonSoundData, flags: int = 0, valid_params: int = 0, params: carb.audio.VoiceParams = None, loop_point: carb.audio.EventPoint = None, play_start: int = 0, play_end: int = 0, play_units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → carb::audio::PythonVoice

Schedules a sound to be played on a voice.

This schedules a sound object to be played on a voice. The sounds current settings (ie: volume, pitch, playback frame rate, pan, etc) will be assigned to the voice as ‘defaults’ before playing. Further changes can be made to the voice’s state at a later time without affecting the sound’s default settings.

Once the sound finishes playing, it will be implicitly unassigned from the voice. If the sound or voice have a callback set, a notification will be received for the sound having ended.

If the playback of this sound needs to be stopped, it must be explicitly stopped from the returned voice object using stopVoice(). This can be called on a single voice or a voice group.

Parameters

sound – The sound to schedule.
flags – Flags that alter playback behavior. Must be a combination of PLAY_FLAG_* constants.
valid_params – Which parameters in the params argument to use.
params – The starting parameters for the voice. This conditionally used based on valid_params.
loop_point – A descriptor for how to repeatedly play the sound. This can be None to only play once.
play_start – The start offset to begin playing the sound at. This is measured in play_units.
play_end – The stop offset to finish playing the sound at. This is measured in play_units.
play_units –
The units in which play_start and play_stop are measured.

Returns:
A new voice handle representing the playing sound. Note that if no buses are currently available to play on or the voice’s initial parameters indicated that it is not currently audible, the voice will be virtual and will not be played. The voice handle will still be valid in this case and can be operated on, but no sound will be heard from it until it is determined that it should be converted to a real voice. This can only occur when the update() function is called. This voice handle does not need to be closed or destroyed. If the voice finishes its play task, any future calls attempting to modify the voice will simply fail.

None if the requested sound is already at or above its instance limit and the PLAY_FLAG_MAX_INSTANCES_SIMULATE flag is not used.

None if the play task was invalid or could not be started properly. This can most often occur in the case of streaming sounds if the sound’s original data could not be opened or decoded properly.

set_parameters(self: carb.audio.Context, paramsToSet: int, params: carb.audio.ContextParams) → None

Sets one or more parameters on a context.

This sets one or more context parameters in a single call. Only parameters that have their corresponding flag set in paramsToSet will be modified. If a change is to be relative to the context’s current parameter value, the current value should be retrieved first, modified, then set.

Parameters

paramsToSet – The set of flags to indicate which parameters in the parameter block params are valid and should be set on the context. This may be zero or more of the CONTEXT_PARAM_* bitflags. If this is 0, the call will be treated as a no-op.
params – The parameter(s) to be set on the context. The flags indicating which parameters need to be set are given in paramsToSet. Undefined behavior may occur if a flag is set but its corresponding value(s) have not been properly initialized. This may not be None.

Returns

No return value.

class carb.audio.ContextCaps: The capabilities of the context object. Some of these values are set at the creation time of the context object. Others are updated when speaker positions are set or an output device is opened.

class carb.audio.ContextParams: Context parameters block. This can potentially contain all of a context’s parameters and their current values. This is used to both set and retrieve one or more of a context’s parameters in a single call. The set of fContextParam* flags that are passed to getContextParameter() or setContextParameter() indicates which values in the block are guaranteed to be valid.

class carb.audio.ContextParams2: Extended context parameters block. This is used to set and retrieve extended context parameters and their current values. This object must be attached to the ‘ContextParams.ext’ value and the ‘ContextParams.flags’ value must have one or more flags related to the extended parameters set for them to be modified or retrieved.

class carb.audio.DeviceCaps

property channels

property flags

property format

property frame_rate

get_name(self: carb.audio.DeviceCaps) → str

property guid

property index

class carb.audio.DspValuePair

property inner

property outer

class carb.audio.EmitterAttributes

property cone

property flags

property forward

property position

property rolloff

property up

property velocity

class carb.audio.EntityAttributes

base spatial attributes of the entity. This includes its position, orientation, and velocity and an optional cone.

property cone

property flags

property forward

property position

property up

property velocity

class carb.audio.EntityCone

defines a sound cone relative to an entity’s front vector. It is defined by two angles - the inner and outer angles. When the angle between an emitter and the listener (relative to the entity’s front vector) is smaller than the inner angle, the resulting DSP value will be the ‘inner’ value. When the emitter-listener angle is larger than the outer angle, the resulting DSP value will be the ‘outer’ value. For emitter-listener angles that are between the inner and outer angles, the DSP value will be interpolated between the inner and outer angles. If a cone is valid for an entity, the @ref fEntityFlagCone flag should be set in @ref EntityAttributes::flags.

Note that a cone’s effect on the spatial volume of a sound is purely related to the angle between the emitter and listener. Any distance attenuation is handled separately.

property inside_angle

property low_pass_filter

property outside_angle

property reverb

property volume

class carb.audio.EventPoint

property frame

property id

property length

property loop_count

property play_index

class carb.audio.IAudioData

create_empty_sound(self: carb.audio.IAudioData, format: carb.audio.SampleFormat, channels: int, frame_rate: int, buffer_length: int, units: carb.audio.UnitType = <UnitType.FRAMES: 1>, name: str = None, channel_mask: int = 0) → carb::audio::PythonSoundData

Create a SoundData object with an empty buffer that can be written to.

After creating a SoundData object with this, you will need to call one of the write_buffer_*() functions to load your data into the object, then you will need to call set_valid_length() to indicate how much of the sound now contains valid data.

Parameters

buffer. (decodedFormat The format for the SoundData object's) – Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This defaults to SampleFormat.DEFAULT, which will use float for the buffer.
audio (channels The number of channels of data in each frame of the) – data.
back (frame_rate The number of frames per second that must be played) – for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).
be. (buffer_length How long you want the buffer to) –
to (units How buffer_length will be interpreted. This defaults) – UnitType.FRAMES.
SoundData (name An optional name that can be given to the) – object to make it easier to track. This can be None if it is not needed. This defaults to None.
which (channel_mask The channel mask for the audio data. This specifies) – speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_blob(self: carb.audio.IAudioData, blob: bytes, decodedFormat: carb.audio.SampleFormat = <SampleFormat.DEFAULT: 11>, flags: int = 0, streaming: bool = False, autoStream: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from a data blob in memory

Args:

blob A bytes object which contains the raw data for an audio
file which has some sort of header. Raw PCM data will not work with this function. Note that due to the way python works, these bytes will be copied into the SoundData object’s internal buffer if the sound is streaming.

decodedFormat The format you want the audio to be decoded into.
Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This is only important if you aren’t creating a decoded sound. This defaults to SampleFormat.DEFAULT, which will decode the sound to float for now.

flags Optional flags to change the behavior. This can be any
of: DATA_FLAG_SKIP_METADATA, DATA_FLAG_SKIP_EVENT_POINTS or DATA_FLAG_CALC_PEAKS.

streaming Set to True to create a streaming sound. Streaming
sounds aren’t loaded into memory; the audio data remains in its encoded form in memory and are decoded in chunks as needed. This is mainly useful for compressed formats which will expand when decoded. This defaults to False.

autoStream The threshold in bytes at which the new sound data
object will decide to stream instead of decode into memory. If the decoded size of the sound will be larger than this value, it will be streamed from its original source instead of decoded. Set this to 0 to disable auto-streaming. This defaults to 0.

Returns:
The new sound data if successfully created and loaded.

An exception is thrown if the sound could not be loaded. This could happen if the blob is an unsupported audio format, the blob is corrupt or some other error during decoding.

create_sound_from_file(self: carb.audio.IAudioData, fileName: str, decodedFormat: carb.audio.SampleFormat = <SampleFormat.DEFAULT: 11>, flags: int = 0, streaming: bool = False, autoStream: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from a file on disk.

Args:

filename The name of the file on disk to create the new sound
data object from.

decodedFormat The format you want the audio to be decoded into.
Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This is only important if you aren’t creating a decoded sound. This defaults to SampleFormat.DEFAULT, which will decode the sound to float for now.

flags Optional flags to change the behavior. This can be any
of: DATA_FLAG_SKIP_METADATA, DATA_FLAG_SKIP_EVENT_POINTS or DATA_FLAG_CALC_PEAKS.

streaming Set to True to create a streaming sound. Streaming
sounds aren’t loaded into memory; they remain on disk and are decoded in chunks as needed. This defaults to False.

autoStream The threshold in bytes at which the new sound data
object will decide to stream instead of decode into memory. If the decoded size of the sound will be larger than this value, it will be streamed from its original source instead of decoded. Set this to 0 to disable auto-streaming. This defaults to 0.

Returns:
The new sound data if successfully created and loaded.

An exception is thrown if the sound could not be loaded. This could happen if the file does not exist, the file is not a supported type, the file is corrupt or some other error occurred during decode.

create_sound_from_float_pcm(self: carb.audio.IAudioData, pcm: List[float], channels: int, frame_rate: int, channel_mask: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from raw 32 bit float PCM data.

Parameters

object. (pcm The audio data to load into the SoundData) – This will be copied to an internal buffer in the object.
audio (channels The number of channels of data in each frame of the) – data.
back (frame_rate The number of frames per second that must be played) – for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).
which (channel_mask the channel mask for the audio data. This specifies) – speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_int16_pcm(self: carb.audio.IAudioData, pcm: List[int], channels: int, frame_rate: int, channel_mask: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from raw 16 bit signed integer PCM data.

Parameters

object. (pcm The audio data to load into the SoundData) – This will be copied to an internal buffer in the object.
audio (channels The number of channels of data in each frame of the) – data.
back (frame_rate The number of frames per second that must be played) – for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).
which (channel_mask the channel mask for the audio data. This specifies) – speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_int32_pcm(self: carb.audio.IAudioData, pcm: List[int], channels: int, frame_rate: int, channel_mask: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from raw 32 bit signed integer PCM data.

Parameters

object. (pcm The audio data to load into the SoundData) – This will be copied to an internal buffer in the object.
audio (channels The number of channels of data in each frame of the) – data.
back (frame_rate The number of frames per second that must be played) – for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).
which (channel_mask the channel mask for the audio data. This specifies) – speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_uint8_pcm(self: carb.audio.IAudioData, pcm: List[int], channels: int, frame_rate: int, channel_mask: int = 0) → carb::audio::PythonSoundData

Create a SoundData object from raw 8 bit unsigned integer PCM data.

Parameters

object. (pcm The audio data to load into the SoundData) – This will be copied to an internal buffer in the object.
audio (channels The number of channels of data in each frame of the) – data.
back (frame_rate The number of frames per second that must be played) – for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).
which (channel_mask the channel mask for the audio data. This specifies) – speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

class carb.audio.IAudioPlayback

create_context(self: carb.audio.IAudioPlayback, desc: carb.audio.PlaybackContextDesc = <carb.audio.PlaybackContextDesc object at 0x7f84e23b91f0>) → carb.audio.Context

class carb.audio.LoopPointDesc: Descriptor of a loop point to set on a voice. This may be specified to change the current loop point on a voice with set_Loop_Point().

class carb.audio.PeakVolumes

property channels

property peak_frame

property peak_volume

class carb.audio.PlaybackContextDesc

class carb.audio.RolloffDesc

Descriptor of the rolloff mode and range. The C++ API allows rolloff curves to be set through this struct, but in python you need to use voice.set_rolloff_curve() to do this instead.

property far_distance

property near_distance

property type

class carb.audio.RolloffType

Members:

INVERSE

LINEAR

LINEAR_SQUARE

INVERSE = <RolloffType.INVERSE: 0>

LINEAR = <RolloffType.LINEAR: 1>

LINEAR_SQUARE = <RolloffType.LINEAR_SQUARE: 2>

property name

property value

class carb.audio.SampleFormat

Members:

PCM8

PCM16

PCM24

PCM32

PCM_FLOAT

PCM_COUNT

VORBIS

FLAC

OPUS

MP3

RAW

DEFAULT

COUNT

COUNT = <SampleFormat.COUNT: 12>

DEFAULT = <SampleFormat.DEFAULT: 11>

FLAC = <SampleFormat.FLAC: 7>

MP3 = <SampleFormat.MP3: 9>

OPUS = <SampleFormat.OPUS: 8>

PCM16 = <SampleFormat.PCM16: 1>

PCM24 = <SampleFormat.PCM24: 2>

PCM32 = <SampleFormat.PCM32: 3>

PCM8 = <SampleFormat.PCM8: 0>

PCM_COUNT = <SampleFormat.PCM_COUNT: 5>

PCM_FLOAT = <SampleFormat.PCM_FLOAT: 4>

RAW = <SampleFormat.RAW: 10>

VORBIS = <SampleFormat.VORBIS: 6>

property name

property value

class carb.audio.SoundData

clear_event_points(self: carb.audio.SoundData) → None

Removes all event points from a SoundData object.

Returns: No return value.

get_buffer_as_float(self: carb.audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → List[float]

Retrieve a buffer of audio from the SoundData object in 32 bit float PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in signed 32 bit integer format. The format is a list containing integer data with values in the range [-1.0, 1.0].

get_buffer_as_int16(self: carb.audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in signed 16 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in signed 16 bit integer format. The format is a list containing integer data with values in the range [-32768, 32767].

get_buffer_as_int32(self: carb.audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in signed 32 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in signed 32 bit integer format. The format is a list containing integer data with values in the range [-2147483648, 2147483647].

get_buffer_as_uint8(self: carb.audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in unsigned 8 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in unsigned 8 bit integer format. The format is a list containing integer data with values in the range [0, 255].

get_event_point_by_id(self: carb.audio.SoundData, id: int) → carb.audio.EventPoint

Retrieves a single event point object by its identifier.

Parameters

retrieve. (id The ID of the event point to) –

Returns

The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_by_index(self: carb.audio.SoundData, index: int) → carb.audio.EventPoint

Retrieves a single event point object by its index.

Event point indices are contiguous, so this can be used to enumerate event points alternatively.

Parameters

retrieve. (index The index of the event point to) –

Returns

The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_by_play_index(self: carb.audio.SoundData, index: int) → carb.audio.EventPoint

Retrieves a single event point object by its playlist index.

Event point playlist indices are contiguous, so this can be used to enumerate the playlist.

Parameters

retrieve. (index The playlist index of the event point to) –

Returns

The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_max_play_index(self: carb.audio.SoundData) → int

Retrieve the maximum play index value for the sound.

Returns: This returns the max play index for this SoundData object. This will be 0 if no event points have a play index. This is also the number of event points with playlist indexes, since the playlist index range is contiguous.

get_event_points(self: carb.audio.SoundData) → List[carb.audio.EventPoint]

Retrieves embedded event point information from a sound data object.

This retrieves event point information that was embedded in the sound file that was used to create a sound data object. The event points are optional in the data file and may not be present. If they are parsed from the file, they will also be saved out to any destination file that the same sound data object is written to, provided the destination format supports embedded event point information.

Returns: The list of event points that are embedded in this SoundData object.

get_format(self: carb.audio.SoundData) → carb.audio.SoundFormat

Query the SoundData object’s format.

Returns

For a sound that was decoded on load, this represents the format of the audio data in the SoundData object’s buffer.

For a streaming sound, this returns the format of the underlying sound asset that is being streamed.

get_length(self: carb.audio.SoundData, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → int

Query the SoundData object’s buffer length.

Parameters: UnitType.FRAMES. (units The unit type that will be returned. This defaults to) –
Returns: The length of the SoundData object’s buffer.

get_max_instances(self: carb.audio.SoundData) → int

Query the SoundData object’s max instance count.

This retrieves the current maximum instance count for a sound. This limit is used to prevent too many instances of a sound from being played simultaneously. With the limit set to unlimited, playing too many instances can result in serious performance penalties and serious clipping artifacts caused by too much constructive interference.

Returns: The SoundData object’s max instance count.

get_memory_used(self: carb.audio.SoundData) → int

Query the amount of memory that’s in use by a SoundData object.

This retrieves the amount of memory used by a single sound data object. This will include all memory required to store the audio data itself, to store the object and all its parameters, and the original filename (if any). This information is useful for profiling purposes to investigate how much memory the audio system is using for a particular scene.

Returns: The amount of memory in use by this sound, in bytes.

get_metadata(self: carb.audio.SoundData, tag_name: str) → str

Retrieve a metadata value from a SoundData object by its tag name.

Parameters

name. (tag_name The metadata tag's) –

Returns

This returns the metadata tag value for tag_name.

This returns None if there is no tag under tag_name.

get_metadata_by_index(self: carb.audio.SoundData, index: int) → Tuple[str, str]

Retrieve a metadata tag from a SoundData object by its index.

Parameters

tag. (index The index of the metadata) –

Returns

(metadata tag name, metadata tag value).

This returns (None, None) if there was no tag at the specified index.

Return type

This returns a tuple

get_name(self: carb.audio.SoundData) → str

Retrieve the name of a SoundData object.

Returns

The name that was given to the object.

This will return None if the object has no name.

get_peak_level(self: carb.audio.SoundData) → carb.audio.PeakVolumes

Retrieves or calculates the peak volume levels for a sound if possible.

This retrieves the peak volume level information for a sound. This information is either loaded from the sound’s original source file or is calculated if the sound is decoded into memory at load time. This information will not be calculated if the sound is streamed from disk or memory.

Returns

The peak level information from the SoundData object.

This will throw if peak level information is not embedded in the sound.

get_valid_length(self: carb.audio.SoundData, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → int

Query the SoundData object’s buffer length.

Parameters: to (units The unit type that will be returned. This defaults) – UnitType.FRAMES.
Returns: The length of the SoundData object’s buffer.

is_decoded(self: carb.audio.SoundData) → bool

Query if the SoundData object is decoded or streaming.

Returns: True if the object is decoded. False if the object is streaming.

save_to_file(self: carb.audio.SoundData, file_name: str, format: carb.audio.SampleFormat = <SampleFormat.DEFAULT: 11>, flags: int = 0) → bool

Save a SoundData object to disk as a playable audio file.

Parameters

as. (file_name The path to save this file) –
file. (format The audio format to use when saving this) – PCM formats will save as a WAVE file (.wav).
function. (flags Flags to alter the behavior of this) – This is a bitmask of SAVE_FLAG_* flags.

Returns

True if the SoundData object was saved to disk successfully. False if saving to disk failed.

set_event_points(self: carb.audio.SoundData, eventPoints: List[carb.audio.EventPoint]) → bool

Modifies, adds or removes event points in a SoundData object.

This modifies, adds or removed one or more event points in a sound data object. An event point will be modified if one with the same ID already exists. A new event point will be added if it has an ID that is not already present in the sound data object and its frame offset is valid. An event point will be removed if it has an ID that is present in the sound data object but the frame offset for it is set to EVENT_POINT_INVALID_FRAME. Any other event points with invalid frame offsets (ie: out of the bounds of the stream) will be skipped and cause the function to fail.

If an event point is modified or removed such that the playlist indexes of the event points are no longer contiguous, this function will adjust the play indexes of all event points to prevent any gaps.

Parameters: eventPoints – The event point(s) to be modified or added. The operation that is performed for each event point in the table depends on whether an event point with the same ID already exists in the sound data object. The event points in this table do not need to be sorted in any order.
Returns: True if all of the event points in the table are updated successfully. False if not all event points could be updated. This includes a failure to allocate memory or an event point with an invalid frame offset. Note that this failing doesn’t mean that all the event points failed. This just means that at least failed to be set properly. The new set of event points may be retrieved and compared to the list set here to determine which one failed to be updated.

set_max_instances(self: carb.audio.SoundData, limit: int) → None

Set the SoundData object’s max instance count.

This sets the new maximum playing instance count for a sound. This limit will prevent the sound from being played until another instance of it finishes playing or simply cause the play request to be ignored completely. This should be used to limit the use of frequently played sounds so that they do not cause too much of a processing burden in a scene or cause too much constructive interference that could lead to clipping artifacts. This is especially useful for short sounds that are played often (ie: gun shots, foot steps, etc). At some [small] number of instances, most users will not be able to tell if a new copy of the sound played or not.

Parameters: set. (limit The max instance count to) –

set_metadata(self: carb.audio.SoundData, tag_name: str, tag_value: str) → bool

Add a metadata tag to a SoundData object.

Metadata tag names are not case sensitive.

It is not guaranteed that a given file type will be able to store arbitrary key-value pairs. RIFF files (.wav), for example, store metadata tags under 4 character codes, so only metadata tags that are known to this plugin, such as META_DATA_TAG_ARTIST or tags that are 4 characters in length can be stored. Note this means that storing 4 character tags beginning with ‘I’ runs the risk of colliding with the known tag names (e.g. ‘IART’ will collide with META_DATA_TAG_ARTIST when writing a RIFF file).

tag_name must not contain the character ‘=’ when the output format encodes its metadata in the Vorbis Comment format (SampleFormat.VORBIS and SampleFormat.FLAC do this). ‘=’ will be replaced with ‘_’ when encoding these formats to avoid the metadata being encoded incorrectly. Additionally, the Vorbis Comment standard states that tag names must only contain characters from 0x20 to 0x7D (excluding ‘=’) when encoding these formats.

Parameters

name. (tag_name The metadata tag's) –
value. (tag_value The metadata tag's) –

Returns

No return value.

set_valid_length(self: carb.audio.SoundData, length: int, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → None

Set the length of the valid portion of the SoundData object’s buffer.

Parameters

set. (length The new valid length to be) –
UnitType.FRAMES. (units How length will be interpreted. This defaults to) –

Returns

The length of the SoundData object’s buffer.

write_buffer_with_float(self: carb.audio.SoundData, data: List[float], offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with 32 bit float PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as float.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_int16(self: carb.audio.SoundData, data: List[int], offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with signed 16 bit PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as int16_t.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_int32(self: carb.audio.SoundData, data: List[int], offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with signed 32 bit PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as int32_t.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_uint8(self: carb.audio.SoundData, data: List[int], offset: int = 0, units: carb.audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with unsigned 8 bit PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as uint8_t.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

class carb.audio.SoundFormat

property bits_per_sample

property block_size

property channel_mask

property channels

property format

property frame_rate

property frame_size

property frames_per_block

property valid_bits_per_sample

class carb.audio.Speaker

Members:

FRONT_LEFT

FRONT_RIGHT

FRONT_CENTER

LOW_FREQUENCY_EFFECT

BACK_LEFT

BACK_RIGHT

BACK_CENTER

SIDE_LEFT

SIDE_RIGHT

TOP_FRONT_LEFT

TOP_FRONT_RIGHT

TOP_BACK_LEFT

TOP_BACK_RIGHT

FRONT_LEFT_WIDE

FRONT_RIGHT_WIDE

TOP_LEFT

TOP_RIGHT

COUNT

BACK_CENTER = <Speaker.BACK_CENTER: 6>

BACK_LEFT = <Speaker.BACK_LEFT: 4>

BACK_RIGHT = <Speaker.BACK_RIGHT: 5>

COUNT = <Speaker.COUNT: 17>

FRONT_CENTER = <Speaker.FRONT_CENTER: 2>

FRONT_LEFT = <Speaker.FRONT_LEFT: 0>

FRONT_LEFT_WIDE = <Speaker.FRONT_LEFT_WIDE: 13>

FRONT_RIGHT = <Speaker.FRONT_RIGHT: 1>

FRONT_RIGHT_WIDE = <Speaker.FRONT_RIGHT_WIDE: 14>

LOW_FREQUENCY_EFFECT = <Speaker.LOW_FREQUENCY_EFFECT: 3>

SIDE_LEFT = <Speaker.SIDE_LEFT: 7>

SIDE_RIGHT = <Speaker.SIDE_RIGHT: 8>

TOP_BACK_LEFT = <Speaker.TOP_BACK_LEFT: 11>

TOP_BACK_RIGHT = <Speaker.TOP_BACK_RIGHT: 12>

TOP_FRONT_LEFT = <Speaker.TOP_FRONT_LEFT: 9>

TOP_FRONT_RIGHT = <Speaker.TOP_FRONT_RIGHT: 10>

TOP_LEFT = <Speaker.TOP_LEFT: 15>

TOP_RIGHT = <Speaker.TOP_RIGHT: 16>

property name

property value

class carb.audio.UnitType

Members:

BYTES

FRAMES

MILLISECONDS

MICROSECONDS

BYTES = <UnitType.BYTES: 0>

FRAMES = <UnitType.FRAMES: 1>

MICROSECONDS = <UnitType.MICROSECONDS: 3>

MILLISECONDS = <UnitType.MILLISECONDS: 2>

property name

property value

class carb.audio.Voice

Represents a single instance of a playing sound. A single sound object may be playing on multiple voices at the same time, however each voice may only be playing a single sound at any given time.

get_parameters(self: carb.audio.Voice, params_to_get: int = 4294967295) → carb.audio.VoiceParams

Retrieves one or more parameters for a voice.

This retrieves the current values of one or more of a voice’s parameters. Only the parameter values listed in paramsToGet flags will be guaranteed to be valid upon return.

Parameters: paramsToGet – Flags indicating which parameter values need to be retrieved.
Returns: The requested parameters in a VoiceParams struct. Everything else is default-initialized.

get_play_cursor(self: carb.audio.Voice, type: carb.audio.UnitType) → int

Retrieves the current play cursor position of a voice.

This retrieves the current play position for a voice. This is not necessarily the position in the buffer being played, but rather the position in the sound data object’s stream. For streaming sounds, this will be the offset from the start of the stream. For non-streaming sounds, this will be the offset from the beginning of the sound data object’s buffer.

If the loop point for the voice changes during playback, the results of this call can be unexpected. Once the loop point changes, there is no longer a consistent time base for the voice and the results will reflect the current position based off of the original loop’s time base. As long as the voice’s original loop point remains (ie: setLoopPoint() is never called on the voice), the calculated position should be correct.

It is the caller’s responsibility to ensure that this is not called at the same time as changing the loop point on the voice or stopping the voice.

Parameters

type – The units to retrieve the current position in.

Returns

The current position of the voice in the requested units.

0 if the voice has stopped playing.

The last play cursor position if the voice is paused.

is_playing(self: carb.audio.Voice) → bool

Checks the playing state of a voice.

This checks if a voice is currently playing. A voice is considered playing if it has a currently active sound data object assigned to it and it is not paused.

Parameters: Voice – The voice to check the playing state for.
Returns: True if the requested voice is playing. False if the requested voice is not playing or is paused. False if the given voice handle is no longer valid.

set_balance(self: carb.audio.Voice, pan: float, fade: float) → None

Non-spatial sound positioning. These provide pan and fade values for the voice to give the impression that the sound is located closer to one of the quadrants of the acoustic space versus the others. These values are ignored for spatial sounds.

Parameters

pan –
The non-spatial panning value for a voice. This is 0.0 to have the sound “centered” in all speakers. This is -1.0 to have the sound balanced to the left side. This is 1.0 to have the sound balanced to the right side. The way the sound is balanced depends on the number of channels. For example, a mono sound will be balanced between the left and right sides according to the panning value, but a stereo sound will just have the left or right channels’ volumes turned down according to the panning value. This value is ignored for spatial sounds. The default value is 0.0.

Note that panning on non-spatial sounds should only be used for mono or stereo sounds. When it is applied to sounds with more channels, the results are often undefined or may sound odd.
fade –
The non-spatial fade value for a voice. This is 0.0 to have the sound “centered” in all speakers. This is -1.0 to have the sound balanced to the back side. This is 1.0 to have the sound balanced to the front side. The way the sound is balanced depends on the number of channels. For example, a mono sound will be balanced between the front and back speakers according to the fade value, but a 5.1 sound will just have the front or back channels’ volumes turned down according to the fade value. This value is ignored for spatial sounds. The default value is 0.0.

Note that using fade on non-spatial sounds should only be used for mono or stereo sounds. When it is applied to sounds with more channels, the results are often undefined or may sound odd.

Returns

None

set_doppler_scale(self: carb.audio.Voice, scale: float) → None

Sets the doppler scale value for the voice. This allows the result of internal doppler calculations to be scaled to emulate a time warping effect.

Parameters: scale – This should be near 0.0 to greatly reduce the effect of the doppler calculations, and up to 5.0 to exaggerate the doppler effect. A value of 1.0 will leave the calculated doppler factors unmodified. The default value is 1.0.
Returns: None

set_frequency_ratio(self: carb.audio.Voice, ratio: float) → None

Set The frequency ratio for a voice.

Parameters

ratio –

This will be 1.0 to play back a sound at its normal rate, a value less than 1.0 to lower the pitch and play it back more slowly, and a value higher than 1.0 to increase the pitch and play it back faster. For example, a pitch scale of 0.5 will play back at half the pitch (ie: lower frequency, takes twice the time to play versus normal), and a pitch scale of 2.0 will play back at double the pitch (ie: higher frequency, takes half the time to play versus normal). The default value is 1.0.

On some platforms, the frequency ratio may be silently clamped to an acceptable range internally. For example, a value of 0.0 is not allowed. This will be clamped to the minimum supported value instead.

Note that the even though the frequency ratio can be set to any value in the range from 1/1024 to 1024, this very large range should only be used in cases where it is well known that the particular sound being operated on will still sound valid after the change. In the real world, some of these extreme frequency ratios may make sense, but in the digital world, extreme frequency ratios can result in audio corruption or even silence. This happens because the new frequency falls outside of the range that is faithfully representable by either the audio device or sound data itself. For example, a 4KHz tone being played at a frequency ratio larger than 6.0 will be above the maximum representable frequency for a 48KHz device or sound file. This case will result in a form of corruption known as aliasing, where the frequency components above the maximum representable frequency will become audio artifacts. Similarly, an 800Hz tone being played at a frequency ratio smaller than 1/40 will be inaudible because it falls below the frequency range of the human ear.

In general, most use cases will find that the frequency ratio range of [0.1, 10] is more than sufficient for their needs. Further, for many cases, the range from [0.2, 4] would suffice. Care should be taken to appropriately cap the used range for this value.

Returns

None

set_loop_point(self: carb.audio.Voice, point: carb.audio.LoopPointDesc) → bool

Sets a new loop point as current on a voice.

This sets a new loop point for a playing voice. This allows for behavior such as sound atlases or sound playlists to be played out on a single voice.

When desc is None or the contents of the descriptor do not specify a new loop point, this will immediately break the loop that is currently playing on the voice. This will have the effect of setting the voice’s current loop count to zero. The sound on the voice will continue to play out its current loop iteration, but will not loop again when it reaches its end. This is useful for stopping a voice that is playing an infinite loop or to prematurely stop a voice that was set to loop a specific number of times. This call will effectively be ignored if passed in a voice that is not currently looping.

For streaming voices, updating a loop point will have a delay due to buffering the decoded data. The sound will loop an extra time if the loop point is changed after the buffering has started to consume another loop. The default buffer time for streaming sounds is currently 200 milliseconds, so this is the minimum slack time that needs to be given for a loop change.

Parameters

voice – the voice to set the loop point on. This may not be nullptr.
point – descriptor of the new loop point to set. This may contain a loop or event point from the sound itself or an explicitly specified loop point. This may be nullptr to indicate that the current loop point should be removed and the current loop broken. Similarly, an empty loop point descriptor could be passed in to remove the current loop point.

Returns

True if the new loop point is successfully set.

False if the voice handle is invalid or the voice has already stopped on its own.

False if the new loop point is invalid, not found in the sound data object, or specifies a starting point or length that is outside the range of the sound data object’s buffer.

set_matrix(self: carb.audio.Voice, matrix: List[float]) → None

Set the channel mixing matrix to use for this voice.

Parameters

matrix –

The matrix to set. The rows of this matrix represent each output channel from this voice and the columns of this matrix represent the input channels of this voice (e.g. this is a inputChannels x outputChannels matrix). Note that setting the matrix to be smaller than needed will result in undefined behavior. The output channel count will always be the number of audio channels set on the context. Each cell in the matrix should be a value from 0.0-1.0 to specify the volume that this input channel should be mixed into the output channel. Setting negative values will invert the signal. Setting values above 1.0 will amplify the signal past unity gain when being mixed.

This setting is mutually exclusive with balance; setting one will disable the other. This setting is only available for spatial sounds if PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX if set in the playback mode parameter. Multi-channel spatial audio is interpreted as multiple emitters existing at the same point in space, so a purely spatial voice cannot have an output matrix specified.

Setting this to None will reset the matrix to the default for the given channel count. The following table shows the speaker modes that are used for the default output matrices. Voices with a speaker mode that is not in the following table will use the default output matrix for the speaker mode in the following table that has the same number of channels. If there is no default matrix for the channel count of the @ref Voice, the output matrix will have 1.0 in the any cell (i, j) where i == j and 0.0 in all other cells.

Returns

None

set_mute(self: carb.audio.Voice, mute: bool) → None

Sets the mute state for a voice.

Parameters: mute – When this is set to true, the voice’s output will be muted. When this is set to false, the voice’s volume will be restored to its previous level. This is useful for temporarily silencing a voice without having to clobber its current volume level or affect its emitter attributes.
Returns: None

set_occlusion(self: carb.audio.Voice, direct: float, reverb: float) → None

Sets the occlusion factors for a voice. These values control automatic low pass filters that get applied to the Sets spatial sounds to simulate object occlusion between the emitter and listener positions.

Parameters

direct – The occlusion factor for the direct path of the sound. This is the path directly from the emitter to the listener. This factor describes how occluded the sound’s path actually is. A value of 1.0 means that the sound is fully occluded by an object between the voice and the listener. A value of 0.0 means that the sound is not occluded by any object at all. This defaults to 0.0. This factor multiplies by EntityCone.low_pass_filter, if a cone with a non 1.0 lowPassFilter value is specified. Setting this to a value outside of [0.0, 1.0] will result in an undefined low pass filter value being used.
reverb – The occlusion factor for the reverb path of the sound. This is the path taken for sounds reflecting back to the listener after hitting a wall or other object. A value of 1.0 means that the sound is fully occluded by an object between the listener and the object that the sound reflected off of. A value of 0.0 means that the sound is not occluded by any object at all. This defaults to 1.0.

Returns

None

set_parameters(self: carb.audio.Voice, params_to_set: int, params: carb.audio.VoiceParams) → None

Sets one or more parameters on a voice.

This sets one or more voice parameters in a single call. Only parameters that have their corresponding flag set in paramToSet will be modified. If a change is to be relative to the voice’s current parameter value, the current value should be retrieved first, modified, then set.

Parameters

paramsToSet – Flags to indicate which of the parameters need to be updated. This may be one or more of the fVoiceParam* flags. If this is 0, this will simply be a no-op.
params – The parameter(s) to be set on the voice. The flags indicating which parameters need to be set must be set in paramToSet by the caller. Undefined behavior may occur if a flag is set but its corresponding value(s) have not been properly initialized. This may not be None.

Returns

No return value.

set_playback_mode(self: carb.audio.Voice, playback_mode: int) → None

Set flags to indicate how a sound is to be played back. This controls whether the sound is played as a spatial or non-spatial sound and how the emitter’s attributes will be interpreted (ie: either world coordinates or listener relative).

PLAYBACK_MODE_MUTED and PLAYBACK_MODE_PAUSED are ignored here; you’ll need to use voice.set_mute() or voice.pause() to mute or pause the voice.

Parameters: playback_mode – The playback mode flag set to set.
Returns: None

set_position(self: carb.audio.Voice, position: carb._carb.Float3) → None

Set the voice’s position.

Parameters: position – The current position of the voice in world units. This should only be expressed in meters if the world units scale is set to 1.0 for this context.
Returns: None

set_priority(self: carb.audio.Voice, priority: int) → None

Set the playback priority of this voice.

Parameters: priority – This is an arbitrary value whose scale is defined by the host app. A value of 0 is the default priority. Negative values indicate lower priorities and positive values indicate higher priorities. This priority value helps to determine which voices are the most important to be audible at any given time. When all buses are busy, this value will be used to compare against other playing voices to see if it should steal a bus from another lower priority sound or if it can wait until another bus finishes first. Higher priority sounds will be ensured a bus to play on over lower priority sounds. If multiple sounds have the same priority levels, the louder sound(s) will take priority. When a higher priority sound is queued, it will try to steal a bus from the quietest sound with lower or equal priority.
Returns: None

set_rolloff_curve(self: carb.audio.Voice, type: carb.audio.RolloffType, near_distance: float, far_distance: float, volume: List[carb._carb.Float2] = [], low_frequency: List[carb._carb.Float2] = [], low_pass_direct: List[carb._carb.Float2] = [], low_pass_reverb: List[carb._carb.Float2] = [], reverb: List[carb._carb.Float2] = []) → None

Set custom rolloff curves on the voice.

Parameters

type – The default type of rolloff calculation to use for all DSP values that are not overridden by a custom curve.
near_distance – The near distance range for the sound. This is specified in arbitrary world units. When a custom curve is used, this near distance will map to a distance of 0.0 on the curve. This must be less than the far_distance distance. The near distance is the closest distance that the emitter’s attributes start to rolloff at. At distances closer than this value, the calculated DSP values will always be the same as if they were at the near distance.
far_distance – The far distance range for the sound. This is specified in arbitrary world units. When a custom curve is used, this far distance will map to a distance of 1.0 on the curve. This must be greater than the @ref nearDistance distance. The far distance is the furthest distance that the emitters attributes will rolloff at. At distances further than this value, the calculated DSP values will always be the same as if they were at the far distance (usually silence). Emitters further than this distance will often become inactive in the scene since they cannot be heard any more.
volume – The custom curve used to calculate volume attenuation over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating volume attenuation. If this is an empty array, the parameter will be ignored.
low_frequency – The custom curve used to calculate low frequency effect volume over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low frequency effect volume. If this is an empty array, the parameter will be ignored.
low_pass_reverb – The custom curve used to calculate low pass filter parameter on the direct path over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.
low_pass_reverb – The custom curve used to calculate low pass filter parameter on the reverb path over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.
reverb – The custom curve used to calculate reverb mix level over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the @ref farDistance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.

Returns

None

set_spatial_mix_level(self: carb.audio.Voice, level: float) → None

Sets the spatial mix level for the voice.

Parameters

level –

The mix between the results of a voice’s spatial sound calculations and its non-spatial calculations. When this is set to 1.0, only the spatial sound calculations will affect the voice’s playback. This is the default when state. When set to 0.0, only the non-spatial sound calculations will affect the voice’s playback. When set to a value between 0.0 and 1.0, the results of the spatial and non-spatial sound calculations will be mixed with the weighting according to this value. This value will be ignored if PLAYBACK_MODE_SPATIAL is not set. The default value is 1.0. Values above 1.0 will be treated as 1.0. Values below 0.0 will be treated as 0.0.

PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX affects the non-spatial mixing behavior of this parameter for multi-channel voices. By default, a multi-channel spatial voice’s non-spatial component will treat each channel as a separate mono voice. With the PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX flag set, the non-spatial component will be set with the specified output matrix or the default output matrix.

Returns

None

set_velocity(self: carb.audio.Voice, velocity: carb._carb.Float3) → None

Set the voice’s velocity.

Parameters: velocity – The current velocity of the voice in world units per second. This should only be expressed in meters per second if the world units scale is set to 1.0 with for the context. The magnitude of this vector will be taken as the listener’s current speed and the vector’s direction will indicate the listener’s current direction. This vector should not be normalized unless the listener’s speed is actually 1.0 units per second. This may be a zero vector if the listener is not moving.
Returns: None

set_volume(self: carb.audio.Voice, volume: float) → None

The volume level for the voice.

Parameters: volume – The volume to set. This should be 0.0 for silence or 1.0 for normal volume. A negative value may be used to invert the signal. A value greater than 1.0 will amplify the signal. The volume level can be interpreted as a linear scale where a value of 0.5 is half volume and 2.0 is double volume. Any volume values in decibels must first be converted to a linear volume scale before setting this value.
Returns: None

stop(self: carb.audio.Voice) → None

Stops playback on a voice.

This stops a voice from playing its current sound. This will be silently ignored for any voice that is already stopped or for an invalid voice handle. Once stopped, the voice will be returned to a ‘free’ state and its sound data object unassigned from it. The voice will be immediately available to be assigned a new sound object to play from.

This will only schedule the voice to be stopped. Its volume will be implicitly set to silence to avoid a popping artifact on stop. The voice will continue to play for one more engine cycle until the volume level reaches zero, then the voice will be fully stopped and recycled. At most, 1ms of additional audio will be played from the voice’s sound.

Parameters: Arguments. (No) –
Returns: No return value.

class carb.audio.VoiceParamBalance

property fade

property pan

class carb.audio.VoiceParamOcclusion

property direct

property reverb

class carb.audio.VoiceParams

Voice parameters block. This can potentially contain all of a voice’s parameters and their current values. This is used to both set and retrieve one or more of a voice’s parameters in a single call. The VOICE_PARAM_* flags that are passed to set_voice_parameters() or get_voice_parameters() determine which values in this block are guaranteed to be valid. The matrix parameter isn’t available from this struct due to limitations in python; use voice.set_matrix() instead.

property balance

property doppler_scale

property emitter

property frequency_ratio

property occlusion

property playback_mode

property priority

property spatial_mix_level

property volume

carb.audio.acquire_data_interface(plugin_name: str = None, library_path: str = None) → carb.audio.IAudioData

carb.audio.acquire_playback_interface(plugin_name: str = None, library_path: str = None) → carb.audio.IAudioPlayback

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') → carb.datasource._datasource.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() → carb.dictionary._dictionary.IDictionary: Returns cached carb.dictionary.IDictionary interface (shorthand).

carb.dictionary.get_dictionary_interface() → carb.dictionary._dictionary.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) → 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.

Returns

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

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.

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.get_eventdispatcher() → carb.eventdispatcher._eventdispatcher.IEventDispatcher: Returns cached carb.eventdispatcher.IEventDispatcher interface (shorthand).

carb.eventdispatcher.get_eventdispatcher_interface() → carb.eventdispatcher._eventdispatcher.IEventDispatcher: Returns cached carb.eventdispatcher.IEventDispatcher 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.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 pop order by name of subscription. Return None if subscription was not found.

get_subscription_to_push_order(self: carb.events._events.IEventStream, name: str) → object: Get subscription to push order by name of subscription. Return None if subscription was not found.

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.ISubscription

Subscription holder.

property name

Returns the name of this subscription.

Returns: The name of this subscription.

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

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

carb.events.get_events_interface() → carb.events._events.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

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

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

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() → carb.settings._settings.ISettings: Returns cached carb.settings.ISettings interface (shorthand).

carb.settings.get_settings_interface() → carb.settings._settings.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() → carb.simplegui._simplegui.ISimpleGui: Returns cached carb.simplegui.ISimpleGui interface (shorthand).

carb.simplegui.get_simplegui_interface() → carb.simplegui._simplegui.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() → carb.tokens._tokens.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() → carb.variant._variant.IVariant: Returns cached carb.variant.IVariant interface (shorthand).

carb.variant.get_variant_interface() → carb.variant._variant.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

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.

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>

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>

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() → omni.ext._extensions.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: Optional[str] = None, archive_subdir: Optional[str] = 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::logging::Logger) → None: Replays recorded log messages for the specified target.

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 as deprecated. It will result in warn log when the function is used.

omni.kit.app.get_app() → omni.kit.app._app.IApp: Returns cached omni.kit.app.IApp interface. (shorthand)

omni.kit.app.get_app_interface() → omni.kit.app._app.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: omni.log._log.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.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.

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

Note: the mask may be 0 if out of range of 64 bits. 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.

@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 make also be @ref 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 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.IMemoryInfo

Interface to collect and retrieve information about memory installed in the system.

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

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.

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.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