Skip to content

Commit

Permalink
Corrected links
Browse files Browse the repository at this point in the history
  • Loading branch information
EPNW-Eric committed Jun 7, 2021
1 parent f758d05 commit 60641e6
Show file tree
Hide file tree
Showing 5 changed files with 14 additions and 11 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
## [0.7.1]
* Fixing dead links

## [0.7.0]
* Initial release
* No struct support yet
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ While `web_ffi` tries to mimic the `dart:ffi` API as close as possible, there ar
* `web_ffi` was designed with the [dart:ffi API 2.12.0](https://api.dart.dev/stable/2.12.0/dart-ffi/dart-ffi-library.html) in mind, so there are currently no array extensions (they came with dart 2.13.0)
* There is currently no support for structs (but opaque stucts are available).
* There are some classes and functions that are present in `web_ffi` but not in `dart:ffi`; such things are annotated with [`@extra`](https://pub.dev/documentation/web_ffi/latest/web_ffi_meta/extra-constant.html).
* There is a new class [`Memory`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Memory-class.html) which is **IMPORTANT** and explained in deepth below.
* The [`DynamicLibrary`](https://pub.dev/documentation/web_ffi/latest/web_ffi/DynamicLibrary-class.html) class constructor is different and requires an instance of the [`@extra Module` class](https://pub.dev/documentation/web_ffi/latest/web_ffi/Module-class.html) .
* If you extend the [`Opaque`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Opaque-class.html) class, you must register the extended class using [`@extra registerOpaqueType<T>()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/registerOpaqueType.html) before using it! Also, your class MUST NOT have type arguments (what should not be a problem).
* There is a new class [`Memory`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/Memory-class.html) which is **IMPORTANT** and explained in deepth below.
* The [`DynamicLibrary`](https://pub.dev/documentation/web_ffi/latest/web_ffi/DynamicLibrary-class.html) class constructor is different and requires an instance of the [`@extra Module` class](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/Module-class.html) .
* If you extend the [`Opaque`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Opaque-class.html) class, you must register the extended class using [`@extra registerOpaqueType<T>()`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/registerOpaqueType.html) before using it! Also, your class MUST NOT have type arguments (what should not be a problem).
* There are some rules concerning interacting with native functions, as listed below.

## Rules for functions
Expand All @@ -26,11 +26,11 @@ There are some rules and things to notice when working with functions:
* You may nest the pointer type up to two times but not more:
* e.g. `Pointer<Int32>` and `Pointer<Pointer<Int32>>` are allowed but `Pointer<Pointer<Pointer<Int32>>>` is not.
* If the return type is `Pointer<NativeFunction>` you MUST use `Pointer<NativeFunction<dynamic>>`, everything else will fail. You can restore the type arguments afterwards yourself using casting. On the other hand, as stated above, type arguments for `NativeFunction`s are just ignored anyway.
* To concretize the things above, [return_types.md](./return_types.md) lists what may be used as return type, everyhing else will cause a runtime error.
* To concretize the things above, [return_types.md](https://github.com/EPNW/web_ffi/tree/master/return_types.md) lists what may be used as return type, everyhing else will cause a runtime error.
* WORKAROUND: If you need something else (e.g. `Pointer<Pointer<Pointer<Double>>>`), use `Pointer<IntPtr>` and cast it yourselfe afterwards using [`Pointer.cast()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Pointer/cast.html).

## Memory
The first call you sould do when you want to use `web_ffi` is [`Memory.init()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Memory/init.html). It has an optional parameter where you can adjust your pointer size. The argument defaults to 4 to represent 32bit pointers, if you use wasm64, call `Memory.init(8)`.
The first call you sould do when you want to use `web_ffi` is [`Memory.init()`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/Memory/init.html). It has an optional parameter where you can adjust your pointer size. The argument defaults to 4 to represent 32bit pointers, if you use wasm64, call `Memory.init(8)`.
Contraty to `dart:ffi` where the dart process shares all the memory, on `WebAssembly`, each instance is bound to a `WebAssembly.Memory` object. For now, we assume that every `WebAssembly` module you use has it's own memory. If you think we should change that, open a issue on [GitHub](https://github.com/EPNW/web_ffi/) and report your usecase.
Every pointer you use is bound to a memory object. This memory object is accessible using the [`@extra Pointer.boundMemory`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Pointer/boundMemory.html) field. If you want to create a Pointer using the [`Pointer.fromAddress()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Pointer/Pointer.fromAddress.html) constructor, you may notice the optional `bindTo` parameter. Since each pointer must be bound to a memory object, you can explicitly speficy a memory object here. To match the `dart:ffi` API, the `bindTo` parameter is optional. Because it is optional, there has to be a fallback mechanism if no `bindTo` is specified: The static [`Memory.global`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Memory/global.html) field. If that field is also not set, an exception is thrown when invoking the `Pointer.fromAddress()` constructor.
Every pointer you use is bound to a memory object. This memory object is accessible using the [`@extra Pointer.boundMemory`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Pointer/boundMemory.html) field. If you want to create a Pointer using the [`Pointer.fromAddress()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Pointer/Pointer.fromAddress.html) constructor, you may notice the optional `bindTo` parameter. Since each pointer must be bound to a memory object, you can explicitly speficy a memory object here. To match the `dart:ffi` API, the `bindTo` parameter is optional. Because it is optional, there has to be a fallback mechanism if no `bindTo` is specified: The static [`Memory.global`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/Memory/global.html) field. If that field is also not set, an exception is thrown when invoking the `Pointer.fromAddress()` constructor.
Also, each [`DynamicLibrary`](https://pub.dev/documentation/web_ffi/latest/web_ffi/DynamicLibrary-class.html) is bound to a memory object, which is again accessible with [`@extra DynamicLibrary.boundMemory`](https://pub.dev/documentation/web_ffi/latest/web_ffi/DynamicLibrary/boundMemory.html). This might come in handy, since `Memory` implements the [`Allocator`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Allocator-class.html) class.
6 changes: 3 additions & 3 deletions example/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,11 +105,11 @@ DynamicLibrary openOpus() {
```

### 4.2 For web platforms
Before we can go on actually initalize our [`Module`](https://pub.dev/documentation/web_ffi/latest/web_ffi/Module-class.html) in dart, we need to include `libopus.wasm` and `libopus.js` in our project. There are several ways to do that. First we will discuss the theoretical background. Than you can decide if you want to follow our sample to include the files or know a way that is more suited for your project.
Before we can go on actually initalize our [`Module`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/Module-class.html) in dart, we need to include `libopus.wasm` and `libopus.js` in our project. There are several ways to do that. First we will discuss the theoretical background. Than you can decide if you want to follow our sample to include the files or know a way that is more suited for your project.
`web_ffi` will bind against your web runtime, access the global JavaScript object and expect to find a property named `libopus`, which holds a function (the so called `module-function`) that takes one argument (we will refer to this argument as `arg0`). Usually, all this is already written in `libopus.js`, so we need to include that file. If the `module-function` is later called from inside dart, it will try to instantiate the actuall WebAssembly instance. Since we compiled with emscripten, the `module-function` follows the standard emscripten approaches to try to get `libopus.wasm`. This means it will firstly check if `arg0['wasmBinary']` contains the bytes of `libopus.wasm`, and if so, use them. If not it will try to access `libopus.wasm` via http(s) from the same site `libopus.js` is included in.

#### 4.2.1 With flutter
We don't want to alter the files flutter puts out after building, so we will include everyhing we need into the flutter app. For `libopus.js` and `libopus.wasm`, we include them as flutter assets, to later inject the JavaScript from the assets into the runtime, we use the [inject_js](https://pub.dev/packages/inject_js) plugin. Lastly, we will use the [`EmscriptenModule.compile()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/EmscriptenModule/compile.html) function with bytes also loaded from the assets to use the `arg0['wasmBinary']` approach. So we need to update our `pubspec.yaml`:
We don't want to alter the files flutter puts out after building, so we will include everyhing we need into the flutter app. For `libopus.js` and `libopus.wasm`, we include them as flutter assets, to later inject the JavaScript from the assets into the runtime, we use the [inject_js](https://pub.dev/packages/inject_js) plugin. Lastly, we will use the [`EmscriptenModule.compile()`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/EmscriptenModule/compile.html) function with bytes also loaded from the assets to use the `arg0['wasmBinary']` approach. So we need to update our `pubspec.yaml`:
```yaml
name: web_ffi_example_flutter
publish_to: 'none'
Expand Down Expand Up @@ -194,7 +194,7 @@ Usually, if we are not using flutter we use `dart2js` what will output a JavaScr
</body>
</html>
```
Then we will use the [`EmscriptenModule.process()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/EmscriptenModule/process.html) function which will internally open the `module-function` with an `arg` without `wasmBinary` set, so the emscripten logic will fetch `libopus.wasm` automatically.
Then we will use the [`EmscriptenModule.process()`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/EmscriptenModule/process.html) function which will internally open the `module-function` with an `arg` without `wasmBinary` set, so the emscripten logic will fetch `libopus.wasm` automatically.
Here is our `lib/src/init_web.dart`:
```dart
// Notice that in this file, we import web_ffi and not proxy_ffi.dart
Expand Down
2 changes: 1 addition & 1 deletion pubspec.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: web_ffi
version: 0.7.0
version: 0.7.1
repository: https://github.com/EPNW/web_ffi/
description: Translates dart:ffi calls on the web to WebAssembly using dart:js

Expand Down
2 changes: 1 addition & 1 deletion return_types.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ Allowed return types for functions used as type parameter in [`NativeFunctionPoi
* `Pointer<Opaque>`, `Pointer<Pointer<Opaque>>`
* `Pointer<Void>`, `Pointer<Pointer<Void>>`
* `Pointer<NativeFunction<dynamic>>`, `Pointer<Pointer<NativeFunction<dynamic>>>`
* `Pointer<MyOpaque>`, `Pointer<Pointer<MyOpaque>>` where `MyOpaque` is a class extending `Opaque` and was registered before using [`registerOpaqueType<MyOpaque>()`](https://pub.dev/documentation/web_ffi/latest/web_ffi/registerOpaqueType.html)
* `Pointer<MyOpaque>`, `Pointer<Pointer<MyOpaque>>` where `MyOpaque` is a class extending `Opaque` and was registered before using [`registerOpaqueType<MyOpaque>()`](https://pub.dev/documentation/web_ffi/latest/web_ffi_modules/registerOpaqueType.html)

0 comments on commit 60641e6

Please sign in to comment.