Struct dome_cloomnik::Context

#[repr(transparent)]pub struct Context<'a>(_, _);

A context is the gate to all of DOME's functionalities for plugins.

You get a context for each callback, and you can retrieve it from WrenVM via get_context(), for use in foreign methods.

Note that you should not keep a context while giving the control back to DOME, and this is enforced by Rust's ownership system.

Implementations

impl Context<'_>

pub fn register_module(&self, name: &str, source: &str) -> Result<(), ()>

Register a Wren module that Wren code can import and use the functionalities it provides.

This functions fails if there is already a module with the same name.

It is recommended to use the register_modules! macro instead.

Example

ctx.register_module("my-module", r#"
    class MyClass {}
"#)
.unwrap();

pub unsafe fn register_fn(
    &self,
    module: &str,
    signature: &str,
    method: extern "C" fn(_: VM)
) -> Result<(), ()>

Register a foreign method in module with signature of the following form:

[static ]ClassName.wrenSignature

For more information about DOME signatures, see DOME docs.

For more information about Wren signatures, see Wren docs.

Fails if the same method is already registered.

Safety

This function is unsafe because it is forbidden to register a function that may panic, and/or store the VM instance it gets for later use.

Doing so may lead to Undefined Behavior.

It is recommended to use the register_modules! macro instead, which also solves the above concerns.

Example

ctx.register_module("my-module", r#"
    class MyClass {
        foreign myGetter
    }
"#)
.unwrap();
extern "C" fn my_fn(vm: WrenVM) {}
ctx.register_fn("my-module", "MyClass.myGetter", my_fn).unwrap();

pub unsafe fn register_class(
    &self,
    module_name: &str,
    class_name: &str,
    allocate: extern "C" fn(_: VM),
    finalize: Option<extern "C" fn(_: *mut c_void)>
) -> Result<(), ()>

Register a foreign class in module with allocate and possibly finalizer:

Fails if the same class is already registered.

Safety

This function is unsafe because it is forbidden to register a function that may panic, and/or store the VM instance it gets for later use, and/or an allocator that does not call [WrenVM::set_slot_new_raw_foreign_unchecked()] or [WrenVM::set_slot_new_foreign_unchecked()].

Doing so may lead to Undefined Behavior.

It is recommended to use the register_modules! macro instead, which also solves the above concerns.

Example

ctx.register_module("my-module", r#"
    foreign class MyClass {
        construct new() {}
    }
"#)
.unwrap();
extern "C" fn allocate(vm: WrenVM) {}
extern "C" fn finalize(data: *mut libc::c_void) {}
ctx.register_class("my-module", "MyClass", allocate, Some(finalize)).unwrap();

pub fn lock_module(&self, name: &str)

Locks a module, preventing extending it later.

It is recommended to lock all modules after you finished to register all of their members.

It is even more recommended to use register_modules!, which does so automatically.

pub fn log(&self, text: &str)

Logs text to the DOME-out.log file and possibly to the console.

pub fn create_channel<T: Send + Sync>(
    &self,
    mix: ChannelMix<T>,
    update: ChannelUpdate<T>,
    user_data: T
) -> Channel<T>

Creates a new audio channel, with user data of type T.

mix: A callback that is responsible to generate the next frame.

update: A callback to be called in the free time.

user_data: The user data. Can be retrieved later using Channel::data() and [Channel::data_mut()] (and counterparts in CallbackChannel).

The user data must be safe to transfer and share across threads, because mix is executed on another thread. If you don't need data, you can just use the unit type.

The returned channel is automatically stopped on drop. Use mem::forget() if that isn't the intention.

Trait Implementations

impl<'a> Debug for Context<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.