emscripten-functions 0.3.0

Rust-friendly bindings to various emscripten system functions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# emscripten-functions
[![crates.io badge](https://img.shields.io/crates/v/emscripten-functions.svg)](https://crates.io/crates/emscripten-functions)

This crate contains various emscripten system functions (made with rust-native parameter and return value types) that make programming in rust for emscripten targets easier.
Functions based on ones from the following emscripten headers are available:
- `emscripten`
- `console`
- `websocket` (thanks to the GitHub user @Captainfl4me)

## Examples
For more examples and tips for emscripten in rust refer to my [main project's README](https://github.com/ALEX11BR/emscripten-functions/blob/main/README.md).

### Run javascript from rust

Using the [`emscripten_functions::emscripten::run_script`](src/emscripten.rs) family of functions you can run the javascript you need in your web app.

#### Example
```rust
// The `.escape_unicode()` method makes it safe to pass untrusted user input.
run_script(
    format!(
        r##"
            document.querySelector("#this-is-secure").innerHTML = "{}"
        "##,
        "untrusted user input".escape_unicode()
    )
);
```

### Calling JavaScript functions using the val API

Using the [`emscripten-val`](https://github.com/MoAlyousef/emscripten-val) crate, you can make use of [emscripten's val API](https://emscripten.org/docs/api_reference/val.h.html) to call JavaScript from the Rust side.

#### Example
Example taken from the [`emscripten-val` README](https://github.com/MoAlyousef/emscripten-val/blob/main/README.md):
```rust
use emscripten_functions::emscripten::{run_script, run_script_int};
use emscripten_val::*;

fn main() {
    let a = Val::from_array(&[1, 2]);
    run_script(format!(
        r#"
        console.log(Emval.toValue({}));
    "#,
        a.as_handle() as i32
    ));

    a.call("push", argv![3]);
    run_script(format!(
        r#"
        console.log(Emval.toValue({}));
    "#,
        a.as_handle() as i32
    ));

    let handle = run_script_int("let n = new Number('123'); Emval.toHandle(n)");
    let number = Val::take_ownership(handle as EM_VAL);
    println!("{}", number.call("valueOf", &[]).as_i32());

    #[no_mangle]
    pub extern "C" fn event_handler(ev: EM_VAL) {
        let val = Val::take_ownership(ev);
        let target = val.get(&"target");
        target.set(&"textContent", &"Clicked");
    }

    let button = Val::take_ownership(run_script_int(
        r#"
        let button = document.createElement('BUTTON');
        button.addEventListener('click', (ev) => {
            _event_handler(Emval.toHandle(ev));
        });
        let body = document.getElementsByTagName('body')[0];
        body.appendChild(button);
        Emval.toHandle(button)
    "#,
    ) as EM_VAL);
    button.set(&"textContent", &"click");
}
```

### Main loop control

If you need to run a loop function over and over, emscripten has its own main loop managing system.
Using the [`emscripten_functions::emscripten::set_main_loop`](src/emscripten.rs) and [`emscripten_functions::emscripten::set_main_loop_with_arg`](src/emscripten.rs) functions you can run your rust functions as main loops, with full control over the main loop running parameters.

#### Example
```rust
struct GameData {
    level: u32,
    score: u32
}
let mut game_data = GameData {
    level: 1,
    score: 0
}

set_main_loop_with_arg(|data| {
    if data.score < data.level {
        data.score += 1;
    } else {
        data.score = 0;
        data.level += 1;
    }

    // Here you call your display to screen functions.
    // For demonstration purposes I chose `println!`.
    println!("Score {}, level {}", data.score, data.level);
}, game_data, 0, true);
```

### An SDL game example

An SDL game example that has image handling can be found [here](../examples/simple-game).

### A websocket sample

A little websocket client application made using [`emscripten_functions::websocket`](src/websocket.rs) can be found [here](../examples/websocket-example).