Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: broken links in assemblyscript examples #164

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion examples/exports/exports.assemblyscript.en-us.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ function addIntegerWithConstant(a: i32, b: i32): i32 {
const ADD_CONSTANT: i32 = 1;
```

Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://docs.assemblyscript.org/details/compiler), which will output a `export-function.wasm`:
Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://www.assemblyscript.org/compiler.html#using-the-compiler), which will output a `export-function.wasm`:

```bash
asc exports.ts -b exports.wasm
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ declare function consoleLog(arg0: i32): void;
consoleLog(24);
```

Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://docs.assemblyscript.org/details/compiler), which will output a `index.wasm`:
Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://www.assemblyscript.org/compiler.html#using-the-compiler), which will output a `index.wasm`:

```bash
asc index.ts -b index.wasm
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Overview

Using buffers and pointers, is a great way to get started with WebAssembly, and drill in its concepts while being productive. But once we start wanting to use higher level data structures efficiently and easily, is where things will get a little more complicated. Thankfully, the AssemblyScript community built [as-bind](https://github.com/torch2424/as-bind), which is a convenient abstraction over [AssemblyScript's loader](https://github.com/AssemblyScript/assemblyscript/tree/master/lib/loader). As mentioned before, `as-bind` abstracts away linear memory, and allows using higher-level data structures between AssemblyScript and JavaScript.
Using buffers and pointers, is a great way to get started with WebAssembly, and drill in its concepts while being productive. But once we start wanting to use higher level data structures efficiently and easily, is where things will get a little more complicated. Thankfully, the AssemblyScript community built [as-bind](https://github.com/torch2424/as-bind), which is a convenient abstraction over [AssemblyScript's loader](https://github.com/AssemblyScript/assemblyscript/tree/main/lib/loader). As mentioned before, `as-bind` abstracts away linear memory, and allows using higher-level data structures between AssemblyScript and JavaScript.

Let's kick things off! To show off how we can use `as-bind`, let's see how we can use strings in WebAssembly and share them with JavaScript:

---

## Implementation

First, we will need to install as-bind into our JavaScript project. If you do not currently have a modern JavaScript project, you can use [`asinit` to generate an AssemblyScript/Javascript project](https://docs.assemblyscript.org/quick-start). After you have generated your project, you can install as-bind by running:
First, we will need to install as-bind into our JavaScript project. If you do not currently have a modern JavaScript project, you can use [`asinit` to generate an AssemblyScript/Javascript project](https://www.assemblyscript.org/getting-started.html#getting-started). After you have generated your project, you can install as-bind by running:

```bash
npm install --save as-bind
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**NOTE: This demo "idea" should not be used in production. As well as the manual type conversions. This is just for learning purposes. The text will contain mentions of when something should not be used.**

As stated before, **WebAssembly is a great fit for computationally intensive tasks**. And even the official [AssemblyScript Documentation covers this](https://docs.assemblyscript.org/faq#is-webassembly-always-faster). For example, Tasks that involve things like big data, heavy logic with conditionals, or nested looping. Thus, generating / rendering audio samples **can** get a significant speedup by moving these mentioned parts into WebAssembly. In this example, we will be amplifying audio samples from an [AudioBuffer](https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer) using the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). **Note:** This functionality can and should be done through a [Gain Node](https://developer.mozilla.org/en-US/docs/Web/API/GainNode), but this is mostly for demonstration purposes. **A more realistic (albeit more complicated and not fit for a demo) use case**, would be to implement unsupported Web Audio API effects like a [bitcrusher](https://github.com/jaz303/bitcrusher) ([Example Video](https://youtu.be/bVcpCswqCXA?t=10)), or a [ogg decoder for unsupported browsers](https://en.wikipedia.org/wiki/HTML5_audio#Supported_audio_coding_formats).
As stated before, **WebAssembly is a great fit for computationally intensive tasks**. And even the official [AssemblyScript Documentation covers this](https://www.assemblyscript.org/frequently-asked-questions.html#is-webassembly-faster-than-javascript). For example, Tasks that involve things like big data, heavy logic with conditionals, or nested looping. Thus, generating / rendering audio samples **can** get a significant speedup by moving these mentioned parts into WebAssembly. In this example, we will be amplifying audio samples from an [AudioBuffer](https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer) using the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). **Note:** This functionality can and should be done through a [Gain Node](https://developer.mozilla.org/en-US/docs/Web/API/GainNode), but this is mostly for demonstration purposes. **A more realistic (albeit more complicated and not fit for a demo) use case**, would be to implement unsupported Web Audio API effects like a [bitcrusher](https://github.com/jaz303/bitcrusher) ([Example Video](https://youtu.be/bVcpCswqCXA?t=10)), or a [ogg decoder for unsupported browsers](https://en.wikipedia.org/wiki/HTML5_audio#Supported_audio_coding_formats).

**Another Note:** This example will continue to build on our simple buffer/pointer memory passing. This could be implemented using higher-level data structures, and these data structures will be covered in later examples.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Overview

As stated before, **WebAssembly is a great fit for computationally intensive tasks**. And even the official [AssemblyScript Documentation covers this](https://docs.assemblyscript.org/faq#is-webassembly-always-faster). For example, Tasks that involve things like big data, heavy logic with conditionals, or nested looping. Thus, generating / rendering graphics **can** get a significant speedup by moving these mentioned parts into WebAssembly. In this example, we will be generating 20x20 colored checkerboard images once per second, and displaying them on a [HTML5 Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) using [Pixel Manipulation on the ImageData Object](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas). In fancy graphics terms, this is a rasterizer.
As stated before, **WebAssembly is a great fit for computationally intensive tasks**. And even the official [AssemblyScript Documentation covers this](https://www.assemblyscript.org/frequently-asked-questions.html#is-webassembly-faster-than-javascript). For example, Tasks that involve things like big data, heavy logic with conditionals, or nested looping. Thus, generating / rendering graphics **can** get a significant speedup by moving these mentioned parts into WebAssembly. In this example, we will be generating 20x20 colored checkerboard images once per second, and displaying them on a [HTML5 Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) using [Pixel Manipulation on the ImageData Object](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas). In fancy graphics terms, this is a rasterizer.

**NOTE:** This example will continue to build on our simple buffer/pointer memory passing. This could be implemented using higher-level data structures, and these data structures will be covered in later examples.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

Another feature of WebAssembly, is its linear memory. Linear memory is a continuous buffer of unsigned bytes that can be read from and stored into by both Wasm and JavaScript. In other words, Wasm memory is an expandable array of bytes that JavaScript and Wasm can synchronously read and modify. Linear memory can be used for many things, one of them being passing values back and forth between Wasm and JavaScript.

In AssemblyScript, the [runtime](https://docs.assemblyscript.org/details/runtime) supports higher level data structures and types. For example, there is support for [Arrays](https://docs.assemblyscript.org/standard-library/array) in AssemblyScript's standard library. But for this example, we will use simple byte (Unsigned 8-bit integer) memory and pointers (Wasm memory array indexes) as a simple(r) way to pass memory back and forth. This is for several reasons:
In AssemblyScript, the [runtime](https://www.assemblyscript.org/runtime.html#runtime) supports higher level data structures and types. For example, there is support for [Arrays](https://www.assemblyscript.org/stdlib/array.html#array) in AssemblyScript's standard library. But for this example, we will use simple byte (Unsigned 8-bit integer) memory and pointers (Wasm memory array indexes) as a simple(r) way to pass memory back and forth. This is for several reasons:

1. Really early versions of AssemblyScript didn't have a Garbage Collector, as at the time it was not part of the spec.
2. Less early versions of AssemblyScript didn't have a runtime, but instead had allocators and manual memory management.
3. Most importantly, we want to show off the concept of linear memory very clearly, in a simple and concise way.

Since we are directly writing to memory in this example, and there exists a runtime in AssemblyScript, **be sure to take a look at the [`--memoryBase` flag in the AssemblyScript compiler](https://docs.assemblyscript.org/details/compiler)**. This flag controls where the AssemblyScript runtime will start writing memory. For example, if you wanted to reserve the first 100 bytes for your own manual memory usage, you could set `--memoryBase 100`. This way AssemblyScript will not write to the first 100 bytes, and only to location 100 and above.Or in other words, `--memoryBase` will allow you to reserve memory for your own manual memory management, and avoid memory being overriden by the AssemblyScript runtime in WebAssembly linear memory.
Since we are directly writing to memory in this example, and there exists a runtime in AssemblyScript, **be sure to take a look at the [`--memoryBase` flag in the AssemblyScript compiler](https://www.assemblyscript.org/compiler.html#linking)**. This flag controls where the AssemblyScript runtime will start writing memory. For example, if you wanted to reserve the first 100 bytes for your own manual memory usage, you could set `--memoryBase 100`. This way AssemblyScript will not write to the first 100 bytes, and only to location 100 and above.Or in other words, `--memoryBase` will allow you to reserve memory for your own manual memory management, and avoid memory being overriden by the AssemblyScript runtime in WebAssembly linear memory.

Let's see how we can use linear memory:

Expand Down Expand Up @@ -40,7 +40,7 @@ export function readWasmMemoryAndReturnIndexOne(): i32 {
}
```

Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://docs.assemblyscript.org/details/compiler), which will output a `index.wasm`:
Then, let's compile that into a wasm module, using the [AssemblyScript Compiler](https://www.assemblyscript.org/compiler.html#using-the-compiler), which will output a `index.wasm`:

```bash
asc index.ts -b index.wasm
Expand Down