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

DIRECTORY

DIRECTORY = <DirectoryItemType.DIRECTORY: 1>
FILE = <DirectoryItemType.FILE: 0>
property name
property value
class carb.filesystem.File
class carb.filesystem.IFileSystem
close_file(self: carb._carb.filesystem.IFileSystem, arg0: carb._carb.filesystem.File) None
copy(self: carb._carb.filesystem.IFileSystem, arg0: str, arg1: str) bool
exists(self: carb._carb.filesystem.IFileSystem, arg0: str) bool
flush_file(self: carb._carb.filesystem.IFileSystem, arg0: carb._carb.filesystem.File) None
get_app_directory_path(self: carb._carb.filesystem.IFileSystem) str
get_current_directory_path(self: carb._carb.filesystem.IFileSystem) str
get_file_size(self: carb._carb.filesystem.IFileSystem, arg0: carb._carb.filesystem.File) int
get_mod_time(self: carb._carb.filesystem.IFileSystem, arg0: str) int
is_directory(self: carb._carb.filesystem.IFileSystem, arg0: str) bool
make_directory(self: carb._carb.filesystem.IFileSystem, arg0: str) bool
make_temp_directory(self: carb._carb.filesystem.IFileSystem) object
open_file_to_append(self: carb._carb.filesystem.IFileSystem, arg0: str) carb._carb.filesystem.File
open_file_to_read(self: carb._carb.filesystem.IFileSystem, arg0: str) carb._carb.filesystem.File
open_file_to_write(self: carb._carb.filesystem.IFileSystem, arg0: str) carb._carb.filesystem.File
remove_directory(self: carb._carb.filesystem.IFileSystem, arg0: str) bool
set_app_directory_path(self: carb._carb.filesystem.IFileSystem, arg0: str) None
set_current_directory_path(self: carb._carb.filesystem.IFileSystem, arg0: str) bool
carb.filesystem.acquire_filesystem(plugin_name: str = None, library_path: str = None) carb._carb.filesystem.IFileSystem

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 0x7f1417850d30>) 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

  2. set_default_action_mapping(self: carb.input.IInput, arg0: carb.input.ActionMappingSet, arg1: str, arg2: carb.input.Gamepad, arg3: carb.input.GamepadInput) -> bool

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

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

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

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

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

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

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

  3. 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
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: