<img width="50%" src="/images/2022/shattered/thumbnail.jpg" style="float: right">

"Shattered" is a new generative and plottable art that will be released the February 23rd, 2022 (6PM Paris time) on the emerging platform https://plottables.io/.

> Shattered [adj] – broken into many small pieces.
>
> This plottable NFT generator visualizes the explosion of polygons (e.g. squares) into pieces then rendered using different filling techniques and suggested inks. There are various rare cases to discovery, like the shape, filling method, alignments,...
>
> The plots are designed to be plotted with fountain pens and on A4 paper, but the plotter artist is free to do any interpretation they want, chose different colors, different paper techniques, the possibilities are endless! Depending on your configuration, the plot can take between 15 minutes to a few hours to execute.
>
> @greweb can ship plotted editions to NFT owners with a small extra cost via https://greweb.me/plots/nft



## Physically plottable?

<video loop autoplay controls src="/images/2022/shattered/video.mp4" width="100%"></video>

Like in [my previous article](https://greweb.me/2021/11/plottable-storm), the generator produces "Plottable NFTs".

A Plottable NFT is, like regular art NFT, a token to a digital artwork that can be sold and resold on a second market – blockchain guarantees its unicity.

The **Plottable** NFT also gives a privilege to its owner: making or requesting a physical plot (with an artistic fee to cover costs, [see /plots/nft](https://greweb.me/plots/nft)). As a physical work can be executed multiple times, every physical piece remain unique: plotting is an analog process that will inevitably yield different results.

<img width="100%" src="/images/2021/11/plottablestorm/schema.png">

[https://greweb.me/plots/nft](https://greweb.me/plots/nft) sets my own "plotting services" terms but any other plotter artist is welcome to collaborate and contribute to offering to the community their own services under their terms and interpretation of the art – I would just ask to verify that the requester owns the NFT.

<img width="100%" src="/images/plots-promo/letters.jpeg">

> You can also be your own artist, buy a plotter, try it out! This is all designed to be open-source friendly and you can download the SVG yourself!

### Prototype, prototype, prototype

Many prototypes have been physically plotted in order to guarantee the viability of results: plottable often is a challenge when it comes to pen and paper. The density is very challenging to adjust: not enough lines and you miss the opportunity for great ink effects and saturation. Try with too much lines and your paper is melting.

<img width="100%" src="/images/2022/shattered/prototypes.jpg">

These prototypes helped to adjust the density and tweak the algorithms over the weeks of development.

<img width="100%" src="/images/2022/shattered/prototype1.jpg">
<img width="100%" src="/images/2022/shattered/prototype3.jpg">
<img width="50%" src="/images/2022/shattered/prototype2.jpg"><img width="50%" src="/images/2022/shattered/prototype5.jpg">
<img width="100%" src="/images/2022/shattered/prototype4.jpg">

## How does the generator work

The generator works in a few steps:

- Step 1 implements **the shattering** and outputs polygons.
- Step 2 implements **the filling**: the polygons are filled with various techniques and colors.
- Step 3 implements **post-processing effects**. Not only a SVG is generated, but it is also used in a WebGL shaders texture to simulate ink and paper effects.

## Step 1: the shattering

The "shattering" is implemented with a recursive function that, given a polygon, randomly cut it in half and apply the same recursion on each part. The cut happens in many different ways. For instance, there is a chance for the "cut" to be aligned with the polygon. The recursion can also randomly stop, which can sometimes keep great parts intact. There is even a very small chance (~0.3%) to not obtain a cut at all and have the original polygon preserved. Parts are usually split near their center and the 2 parts that result from the cut can diverge from each other – this simulates some kind of "pushback" resulting of the shattering.

### 'Shape' feature

The main polygon used before the shattering occurs can vary from a square to a circle, with rare cases of triangles, hexagons,...

Square remains the most common shape to have.

<img width="50%" src="/images/2022/shattered/examples/shape-square.jpg"><img width="50%" src="/images/2022/shattered/examples/shape-circle.jpg"><img width="50%" src="/images/2022/shattered/examples/shape-hexagon.jpg"><img width="50%" src="/images/2022/shattered/examples/shape-pentagon.jpg">

### 'Parts' feature

This feature categorizes the number of polygon parts that result from the shattering. It can vary from one to thousands.

<img width="100%" src="/images/2022/shattered/examples/variety3.jpg">

### 'Pushback' feature

This feature expresses how intense the Pushback is for a given piece – effect that shifts parts away from each other.

<img width="100%" src="/images/2022/shattered/examples/pushback-high.jpg">

It can sometimes not exist at all which make the polygon preserving its general shape and only showing subdivisions:

<img width="100%" src="/images/2022/shattered/examples/pushback-none.jpg">

### 'Alignment' feature

The alignment represents how perpendicular the parts are organized altogether.

This has no alignment:

<img width="50%" src="/images/2022/shattered/examples/alignment-none.jpg">

These have the max alignment:

<img width="50%" src="/images/2022/shattered/examples/alignment-max.jpg"><img width="50%" src="/images/2022/shattered/examples/alignment-max-2.jpg">

### 'Destructed' feature

'Destructed' is a rare feature that expresses that part of the polygons has been destructed. This sometimes happens when the shattered parts are pushbacked out of boundaries.

<img width="50%" src="/images/2022/shattered/examples/destructed-1.jpg"><img width="50%" src="/images/2022/shattered/examples/destructed-2.jpg"><img width="50%" src="/images/2022/shattered/examples/destructed-3.jpg"><img width="50%" src="/images/2022/shattered/examples/destructed-4.jpg">

### 'Distribution' feature

'Distribution' feature expresses the area balance between parts. Here are some examples:

**"One Major"** (2 examples side by side)

<img width="50%" src="/images/2022/shattered/examples/distribution-onemajor-2.jpg"><img width="50%" src="/images/2022/shattered/examples/distribution-onemajor.jpg">

**"Two Main"** (2 examples side by side)

<img width="50%" src="/images/2022/shattered/examples/distribution-twomainparts-2.jpg"><img width="50%" src="/images/2022/shattered/examples/distribution-twomainparts.jpg">

**"Small Parts"** (2 examples side by side)

<img width="50%" src="/images/2022/shattered/examples/distribution-small-parts-2.jpg"><img width="50%" src="/images/2022/shattered/examples/distribution-small-parts-3.jpg">

## Step 2: the filling

each polygon resulting from the shattering is individually filled with various techniques. That said, the shattering algorithm has already decided how each polygon is colored and filled. There is a higher chance that related parts have same fill and color, but it can still happen that one has many different filling techniques on the same piece:

<img width="50%" src="/images/2022/shattered/examples/variety.jpg"><img width="50%" src="/images/2022/shattered/examples/variety2.jpg">

These are statistically the TOP 10 filling technique combination to most likely occur:

```
Statistics of feature 'Fill':
                   Web, Spiral: 6.0%
                           Web: 5.7%
                Web, Ping Pong: 3.3%
                   Spiral, Web: 3.3%
                     Ping Pong: 3.1%
                     Scratches: 2.8%
                         Hatch: 2.5%
          Ping Pong, Scratches: 2.3%
                     Stippling: 2.3%
            Web, Spiral, Empty: 2.2%
```

The 66% remaining is going to many different combinations of one of the 8 different filling technique that can occur: **Empty, Spiral, Web, Ping Pong, Scratches, Hatch, Stippling, Zigzag** which I'm going to detail now:

### Fill = Empty

There is a first, rare filling technique that consists of NOT filling! but simply stroking the polygon. It is mostly used on small polygons and used in combination with another filling technique.

<img width="100%" src="/images/2022/shattered/examples/fill-empty.jpg">

### Fill = Spiral

Spiral is the most complex algorithm of the generator and can take up to a few seconds to run in JavaScript. It works by connecting randomly sampled dots by rotating the lines, each iteration scans for a point making the smallest angle turn, this creates a spiral that statistically converge to the center.

<img width="50%" src="/images/2022/shattered/examples/fill-spiral.jpg"><img width="50%" src="/images/2022/shattered/examples/fill-spiral-3.jpg">

Due to the complexity of the algorithm, I have chosen to bail out some cases to fallback to "Web" filling technique which is why you most likely never get a "Spiral only" filling (it can still happen ~0.4%).

### Fill = Web

The web is, after spiral, the second most popular filling technique to happen but is the most likely technique to happen as "standalone" (without combination with another filling technique)

<img width="50%" src="/images/2022/shattered/examples/fill-web.jpg"><img width="50%" src="/images/2022/shattered/examples/fill-web-3.jpg">

One of the easter eggs of this Fill technique is that it will sometimes also have circles hole that the algorithm will try to avoid:

<img width="100%" src="/images/2022/shattered/examples/fill-web-2.jpg">

The algorithm samples a bunch of points along the polygon edge and connects dots randomly. The dots are connected with lines that maximize avoiding the circles and "traversing" the polygon rather than connecting lines that would be along an edge. Points are also samples randomly away from the polygon edge in order to avoid too much paper density problem – it creates an interesting border width effect.

### Fill = Ping Pong

Ping Pong filling is the idea to throw a ray that bounces on the polygon edge.

<img width="100%" src="/images/2022/shattered/examples/fill-pingpong.jpg">

The basic idea is to sample points along the polygon perimeter and then to do a permutation of indexes that can for instance looks like this: **0, 100, 200, 1, 101, 201, 2, 102, 202,...\***.

Many optimizations were done on this to make the plot viable. Each line is traced by counting how much lines traversed at a given position and will stop as soon as it's too "crowded".

We can notice the algorithm at work on the previous example as we see some "gaps" near the intersection of some lines, but in practice, a plot will be generally fine as the ink will "bleed" a bit and fill these gaps.

### Fill = Hatch

the hatching technique traces parallel lines with a varying distance to produces a fabric pattern. The lines are chosen in a way that they are aligned to the longest segment that can exists inside the polygon.

<img width="50%" src="/images/2022/shattered/examples/fill-hatch.jpg"><img width="50%" src="/images/2022/shattered/examples/fill-hatching-3.jpg">

### Fill = Stippling

the stippling technique is implemented with many samples points from which a small line stroke is done. The line stroke segment, which is one millimeter long, is oriented following a simple field determined with the center of the polygon: `atan2(cx - p[0], cy - p[1])`

<img width="50%" src="/images/2022/shattered/examples/fill-stippling.jpg"><img width="50%" src="/images/2022/shattered/examples/fill-stippling-2.jpg">

### Fill = Scratches

<img width="100%" src="/images/2022/shattered/examples/fill-scratches.jpg">

Scratches are sorting randomly samples points on two perpendicular axis that follow the general polygon direction.

### Fill = Zigzag

<img width="50%" src="/images/2022/shattered/examples/fill-zigzag.jpg"><img width="50%" src="/images/2022/shattered/examples/fill-zigzag-2.jpg">

Zigzag has a similar idea as in Scratches except it only traces line on one axis and will only sample points on the edge.

## Step 3: post-processed effects

To give more life to the digital shape, I have added some paper grain effects as well as a lighting effect that grows from the center.

It is important to note that I actually generate 2 SVGs:

- one dedicated for the WebGL shaders where I use #0FF, #F0F, #FF0 colors and addition mode to be able to tell what even ink there is at a position. It allows me to implement some sort of ink simulation (those which remains minimal, but using opacity to express the saturation of an ink and each color defines 2 colors on each it derives too – for instance the yellow of Diamine Amber is diverging to orange tones)
- a second SVG is the downloadable SVG that tries to approach as much as possible the ink color and have layers ready for the plotter. Note that you can directly drag&drop (or right-click) from the digital canvas itself (thanks to a hidden `<img>` in the DOM)

## Palette

The art pieces are picking colors among a palette of 9 curated inks from Diamine that looks like this:

<img width="100%" src="/images/2022/shattered/inks.jpg">

They are sorted from common to relatively rarer cases.

- Black
- Poppy Red
- Turquoise
- Amazing Amethyst
- Indigo
- Hope Pink
- Amber
- Pumpkin
- Aurora Borealis

The most common case is to obtain a plot that will only have one ink chosen, but the plot can go up to having 3 different colors. They are split into different layers.

<img width="50%" src="/images/2022/shattered/examples/colors-2.jpg"><img width="50%" src="/images/2022/shattered/examples/colors-3.jpg">

## Artistic challenges and choices

To wrap up, it took me quite a lot of iterations to reach decision on many aspects and tweak what would be my final pieces. In generative art and especially when you reach a high variety of results it is really hard to guarantee one given output is satisfying. This is especially true in my case that involve many level of recursion which makes it very hard to control the outcome. The wider your generation is, more likely you will get non interesting results or edge cases you do not prefer to happen. The boundaries of the generation have to be well controlled in order to avoid the "bad cases".

**Total rewrite of my tech stack**. Technically speaking, this generator was a total rework of my stack, which is in Rust, back into pure JavaScript. As the code is on-chain, it needs to be very well optimized in term of bytes and I used many techniques from back of my JS1K / JS13K days! I compressed my GLSL shader code as well as the JavaScript code, I use only tuples (arrays) to represent my data so they do not have the verbosity of JS objects, etc...

**curating away the bad cases**. The way I generally approached the curation in my generator is to curate away the cases I didn't want rather than explicitly curating the cases I want! Typically, one algorithm will control the quality of the output and will be retrying the result until it satisfies the criterias. One example is I have to exclude any "empty result" to happen. I also explicitely wanted to bail out a result containing only one cut (2 polygons).

**Brace for impact**. embracing collisions and allowing some shapes to intersect was part of the "glitch" I wanted to keep. It can be interesting to have a mix of inks that occur on these intersections. This is a rare effect.

**recursion depth**. It took me quite a lot of shattering iteration to decide on the maximum number of recursion I would do as well as it's rarity. At the end, I've chose to make the "low number of parts" rarer than having a very exploded shattered case, because it emphasis on what the piece is about. Pieces that are intacted or only cut in a few parts are still very interesting to have and should actually be quite scarced.

**shapes rarity & filling consistency**. The way the shape are filled are not always decided randomly and many logic bail out from cases I didn't want.

<img width="100%" src="/images/2022/shattered/thumbnail.jpg">

Shattered is a NFT plottable generator that visualizes the explosion of polygons (usually squares) into parts that are rendered with different filling techniques and suggested inks. There are various rarity elements, like the shape, filling method, inks...

Shattered, a plottable generator on plottables.io


This fourth article (in a series of 7 articles) reveals the technique used to render the Nano swivel.

<video muted loop autoplay controls src="/images/2022/gnsp/361.mp4" width="50%" style="float:left; margin-right: 40px; margin-bottom:20px"></video>

**Timeline:**

- [article 1: GNSP – the concept](/2021/12/gnsp)
- [article 2: the 3D distance to a Nano S+](/2021/12/gnsp-raymarching)
- [article 3: the nano screen](/2022/02/gnsp-nanoscreen)
- [**article 4: the swivel**](/2022/02/gnsp-swivel)
- article 5: the background
- article 6: the video generation
- article 7: the final drop
- (?March) public mint

**The collection is browsable on https://greweb.me/gnsp**

**OpenSea: https://opensea.io/collection/gnsp**

<br style="clear:left"/>

This is very similar to the "nano screen" in that we will use a Canvas 2D as a texture to the GLSL shader and it will be projected on the swivel surface.

## The Canvas 2D generative swivel code

A canvas 2D of 1200 x 400 pixels is used to draw the swivel engraved texture. We use it to possibly display a text and draw some "plotted lines".

```js
async function metal(word, swivelPlotted) {
  const w = 1200;
  const h = 400;
  const canvas = document.createElement("canvas");
  canvas.width = w;
  canvas.height = h;
  const ctx = canvas.getContext("2d");
  ctx.fillStyle = "#000";
  ctx.fillRect(0, 0, w, h);
  ctx.fillStyle = "#fff";
  let font = "Arial";
  // ...plot things...
  // ...draw text...
  return canvas;
}
```

Here is what the texture of #472 looks like:

<img src="/images/2022/gnsp/472-texture.png" width="100%" />

and here is the final result in the raymarched object:

<video muted loop autoplay controls src="/images/2022/gnsp/472.mp4" width="100%"></video>


### "plotted" lines

<video muted loop autoplay controls src="/images/2022/gnsp/461.mp4" width="100%"></video>

The swivel can sometimes be "laser plotted" which is a reference to the "plotting" work I've been doing last year. This "plotting" is a simple stacking of lines which create some mountains effect.

In the following code, `swivelPlotted` is defined when plotting is active and is an array of random values.

```js
if (swivelPlotted) {
  ctx.strokeStyle = "#fff";
  ctx.lineWidth = 3;
  const octaveCount = Math.floor(3 + 6 * swivelPlotted[4]);
  const perlin = generatePerlinNoise(w, h, {
    octaveCount,
    amplitude: swivelPlotted[3],
    persistence: 0.2,
  });
  let pad = [50, 20];
  let amp = 120 * mix(swivelPlotted[0], swivelPlotted[1], swivelPlotted[2]);
  let incr = Math.floor(3 + 50 * swivelPlotted[1]);
  if (incr < 15 || (octaveCount < 4 && amp > 40)) {
    ctx.fillStyle = "#000";
    font = "Arial Black";
  }
  let heights = Array(w).fill(h);
  for (let y = h - pad[1]; y > pad[1] + amp; y -= incr) {
    ctx.beginPath();
    let up = true;
    for (let x = pad[0]; x < w - pad[0]; x++) {
      let dy = amp * perlin[y * w + x];
      let yy = y - dy;
      let m = heights[x];
      if (yy > m) {
        up = true;
        continue;
      }
      heights[x] = yy;
      if (up) {
        ctx.moveTo(x, yy);
        up = false;
      } else {
        ctx.lineTo(x, yy);
      }
    }
    ctx.stroke();
  }
}
```


### text

As shown at the beginning, we can also simply have a text on the swivel. Sometimes it is combined with the plotting effect.

<video muted loop autoplay controls src="/images/2022/gnsp/322.mp4" width="100%"></video>

```js
if (word) {
  ctx.textAlign = "center";
  ctx.textBaseline = "middle";
  const lines = word.split("\n");
  const sz = Math.floor(
    20 + 1200 / (3 + Math.max(...lines.map((l) => l.length)))
  );
  ctx.font = sz + "px " + font;
  lines.forEach((line, i) => // multi line
    ctx.fillText(
      line,
      w / 2,
      Math.round(h / 2 + 1.2 * sz * (i + 0.5 - lines.length / 2))
    )
  );
}
```


### sticker text

We can also use emoji instead of text.

<video muted loop autoplay controls src="/images/2022/gnsp/365.mp4" width="100%"></video>

## Raymarching shader integration

The swivel metal texture is rendered using a brownian noise. (like explained in https://thebookofshaders.com/13/)

Contextually to the raymarching, we have the local coordinate of the swivel (including its rotation), which allows us to do a texture lookup on the swivel text texture. All of this information (noise and texture) is encoded in the material value (a float). It is possible to encode it on one value like this because it's a grayscale value.

```glsl
noiseMetal = fbm(vec2(40.0, 1000.) * p.xy);
vec2 coord = fract(vec2(1.0, -3.0) * p.xy + vec2(0.5));
vec4 mt = texture2D(metalText, coord);
float t = mix(0., grayscale(mt.rgb),mt.a * step(p.z, 0.) * step(p.x, -0.5) * step(abs(p.y), 0.16));
float swivelM = 2.2 + t;
s = opU(s, HIT(swivel, swivelM));
```

## sticker emoji

<video muted loop autoplay controls src="/images/2022/gnsp/321.mp4" width="100%"></video>

For the sticker that appear on the swivel, we add to the distance a disc and we use a side effect `vec3 sticker_color` variable that is later used in the `shade` function. The position of the sticker is randomly placed.

```glsl
${
  !opts.sticker
    ? ""
    : `
vec2 q = p.xy + vec2(${opts.stickerPosX.toFixed(2)}, ${opts.stickerPosY.toFixed(2)});
float sticker_size = 0.15;
float sticker_border = 0.01;
coord = fract(vec2(.5,-.5) * q / sticker_size - 0.5);
vec4 v = texture2D(stickerText, coord);
sticker_color = mix(vec3(1.), v.rgb, v.a);
float l = length(q.xy)-sticker_size;
s = opU(s, HIT(max(
  abs(p.z + 0.13)-0.005,
  l-sticker_border
), 4.2 - step(0.0, l)));
`
}
```

This fourth article reveals the technique used to render the Nano swivel.

GNSP – the swivel rendering

This third article (in a series of 7 articles) reveals the technique used to render the screen display itself.

<video muted loop autoplay controls src="/images/2021/12/gnsp/419.mp4" width="50%" style="float:left; margin-right: 40px; margin-bottom:20px"></video>

**Timeline:**

- [article 1: GNSP – the concept](/2021/12/gnsp)
- [article 2: the 3D distance to a Nano S+](/2021/12/gnsp-raymarching)
- [**article 3: the nano screen**](/2022/02/gnsp-nanoscreen)
- [article 4: the swivel](/2022/02/gnsp-swivel)
- article 5: the background
- article 6: the video generation
- article 7: the final drop
- (?March) public mint

**The collection is browsable on https://greweb.me/gnsp**

**OpenSea: https://opensea.io/collection/gnsp**

<br style="clear:left"/>

The screen, displays the unique BIP39 word and can sometimes have an effect or an animation. In the NFT metadata, they are expressed on the "Screen" feature, and here is the distribution:

```
                 <not defined>: 1527 = 74.6%
                     scrolling: 251 = 12.3%
                      blinking: 136 = 6.6%
                      negative: 81 = 4.0%
                       complex: 25 = 1.2%
        negative and scrolling: 11 = 0.5%
                 half-negative: 8 = 0.4%
         negative and blinking: 7 = 0.3%
    half-negative and blinking: 2 = 0.1%
```

This means 75% of the time you will only get the text displayed statically but in other case you have various effects implemented.

## Step 1: a Canvas2D texture is used for the word text

a 128 by 64 Canvas 2D texture is generated – this is the actual resolution in pixels on the actual device.

```js
function screen(word) {
  const w = 128; const h = 64;
  const canvas = document.createElement("canvas");
  canvas.width = w; canvas.height = h;
  const ctx = canvas.getContext("2d");
  ctx.fillStyle = "#fff";
  ctx.fillRect(0, 0, w, h);
  ctx.textAlign = "center";
  ctx.textBaseline = "middle";
  ctx.font =
    (navigator.userAgent.includes("Mac OS")
      ? "" : "bold ") + "22px Arial";
  ctx.fillStyle = "#000";
  ctx.fillText(word, w / 2, h / 2);
  return canvas;
}
```

> Ok, there is a funny trick here on an annoying fact: depending on your OS you will have a different font weight, as Mac devices tend to have bolder font, I only used non bold in other cases. 




Apart this trick, there are nothing fancy here: we are just writing the word in the Canvas. So there are actually no animation logic at all here: the animations (text motion / balls motion in negative) are all implemented in the GLSL shader.


## Step 2: the text texture is processed in GLSL

I'm using `regl` library helper and I need to inject the text canvas as a `uniform sampler2D text` parameter:

```js
uniforms: {
  text: regl.texture({ data: screenCanvas, flipY: true }),
```

After this, the main trick is to project the 2D Texture of the word onto the 3D raymarched object, and in my case, I simply project it along the Z-axis, globally. Indeed it would need to be applied "locally" if the Nano was actually moving or rotating but I didn't need that so we can simply stick to a global mapping.

So basically:

```glsl
vec2 coord = someOffset + someMultiplier * p.xy;
float m = step(texture2D(text, coord).x, 0.5);
```

makes `m` being a value of either 0.0 or 1.0 based on if the pixel is on or off.

Now, it also need to be pixelated, so we need to round the coordinate:

```glsl
vec2 coord = someOffset + someMultiplier * p.xy;
vec2 a = coord * vec2(128.,64.);
coord = floor(a) / vec2(128.,64.);
float m = step(texture2D(text, coord).x, 0.5);
```

Then we add a `edge` effect. This `edge` represents the distance to the edge of a pixel.

```glsl
vec2 coord = someOffset + someMultiplier * p.xy;
vec2 a = coord * vec2(128.,64.);
float edge = min(fract(a.x), fract(a.y));
coord = floor(a) / vec2(128.,64.);
float m = step(texture2D(text, coord).x, 0.5)
  * (1.0 - 0.5 * step(edge, 0.25)); // changes the pixel color
```

This will accentuate even more the pixel effect as we can see in this zoom:

<img src="/images/2022/gnsp/pixel.png" width="100%"/>

Ok, to precise exactly what `coord` is, here is the actual code:

```glsl
vec2 coord = fract(fract(vec2(-0.2, 0.5) + vec2(3.6) * p.xy / vec2(-2.25, 1.0)) + ${
  opts.scrollingScreen ? "vec2(0.5+floor(time*15.0)/15.0, 0.)" : "0.0"
});
```

You can note that:
- multiply by `vec2(-2.25, 1.0)` to stretch a bit the font.
- in case of `scrollingScreen` an offset by `time` is applied on x coordinate, and using some floor function so it does it by "increments" (pixel scroll)
- we apply a whole `fract` function (which is a `% 1.0`) to keep the coord in a 0.0 - 1.0 range and actually make it repeat.

Now, to create the negative effect, what we simply need to do is to either chose `m` or `1.0 - m` as a pixel value. 


This is implementing the simple idea to have half of the screen cut into two negative parts:

```glsl
${opts.halfnegativeScreen ? "m=mix(m,1.-m,step(coord.y, 0.5));" : ""}
```

And this implements the possibly blinking effect:

```glsl
${opts.blinkingScreen ? "m*=step(fract(2.*time),0.5);" : ""}
```

Now for the more complex animation, the effect varies at a given position on x,y, so we will give it to a function to determine if we need to swap the color. The animation we can see in the video above is a reference to one of my last year creation: [/shaderday/65](/shaderday/65).

```glsl
${
  !opts.screenAnimation
    ? ""
    : `
      float sz = ${(
        1 -
        opts.screenAnimation[3] * opts.screenAnimation[3]
      ).toFixed(2)};
      coord -= 0.5;
      coord *= vec2(2.,1.) * ${(
        1 -
        opts.screenAnimation[3] * opts.screenAnimation[3]
      ).toFixed(2)};
      coord += 0.5;
      ${
        opts.screenAnimation[1] < 0.2
          ? `coord.y${opts.screenAnimation[1] < 0.1 ? "+" : "-"}=time;`
          : ""
      }
      ${opts.screenAnimation[2] < 0.2 ? `coord.x-=time;` : ""}
      coord=fract(coord);
      m=mix(m,1.-m,step(shape(coord,2.*PI*time), 0.5));
    `
}
```


`screenAnimation` is a array of random values and with that, we can yield variation of the initial `shape` animation which is implemented relatively like in my [/shaderday/65](/shaderday/65):

```glsl
float shape (vec2 p, float t) {
  float smoothing = 0.15;
  p -= 0.5;
  vec2 q = p;
  pR(p, t + cos(${Math.round(5 * opts.screenAnimation[0] - 2)}. * t));
  vec2 dist = vec2(0.0);
  float crop = 99.0;
  float s = 99.0;;
  s = fOpUnionRound(q.y, s, smoothing);
dist = vec2(0.31, 0.0);
float radius = 0.11;
s = fOpUnionRound(s, length(p + dist) - radius, smoothing);
crop = fOpUnionRound(crop, length(p - dist) - radius, smoothing);
  s = fOpDifferenceRound(s, crop, smoothing);
  return smoothstep(0.0, 1.0 / min(resolution.x, resolution.y), s);
}
```

Finally, we map the "m" value to actual colors, and in our case it's basically black and white. Note the usage of `negativeScreen` flag:

```glsl
mix(
  vec3(0.01),
  vec3(1.0),
  ${opts.negativeScreen ? "1.-" : ""}m
)
```

> This GLSL code is templated in JavaScript as you may notice, it's a trick to make the GLSL compile even faster to avoid having runtime ifs.

**That's it folks! There are nothing more to say about the screen rendering of GNSP.**

This third article reveals the technique used to render the screen display itself.

GNSP – the Nano screen rendering



This second article (in a series of 7 articles) reveals the technique used to 3D render the Generative Nano S Plus collection: using a GLSL fragment shader, without any 3D model, raymarching a calculated distance to a Nano S Plus.

<video muted loop autoplay controls src="/images/2021/12/gnsp/509model.mp4" width="50%" style="float:left; margin-right: 40px; margin-bottom:20px"></video>

**Timeline:**

- [article 1: GNSP – the concept](/2021/12/gnsp)
- [**article 2: the 3D distance to a Nano S Plus**](/2021/12/gnsp-raymarching)
- [article 3: the nano screen](/2022/02/gnsp-nanoscreen)
- [article 4: the swivel](/2022/02/gnsp-swivel)
- article 5: the background
- article 6: the video generation
- article 7: the final drop
- (?March) public mint

**The collection is browsable on https://greweb.me/gnsp**

**OpenSea: https://opensea.io/collection/gnsp**

<br style="clear:left"/>

## The rendering is implemented in a GLSL Fragment Shader

The generative art is rendered entirely into one "fragment shader", which is essentially a GPU program that takes a bunch of inputs and efficiently calculates the pixel colors with your graphic card.

This is a paradigm I like to call "Functional Rendering paradigm": see article https://observablehq.com/@gre/introduction-to-functional-rendering-paradigm

On top of this paradigm, I have used a technique called Raymarching distance function, see article https://observablehq.com/@gre/introduction-to-raymarching-distance-functions

Here is the main algorithm that implement the raymarching: (where `map` is the distance function)

```glsl
HIT marcher (inout vec3 p, vec3 dir) {
  HIT hit = HIT(0.);
  float t = 0.;
  for (int i=0; i<120; i++) {
    HIT h = map(p + t * dir);
    t += h.x;
    if (abs(h.x) < .0001) {
      hit = h;
      break;
    }
  }
  p += t * dir; 
  return hit;
}
```

A fun proof of this is to play with the number of raymarching iteration (modulating iterations from 0 to 120):

<video muted loop autoplay controls src="/images/2021/12/gnsp/glitch.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/glitch2.mp4" width="50%"></video>

The main scene is described in this "map" distance function:

```glsl
HIT map (vec3 position) {
  HIT s = HIT(10. - length(position), 0.);
  float t = 3. * fract(time);
  float swivelAngle = PI * ( 1. +
    cubicInOut(min(1.0, t)) +
    cubicInOut(min(1.0, max(t - 1.8, 0.0))) );
  s = opU(s, sdLedgerNanoSPlus(position, swivelAngle));
  return s;
}
```

## The 3D distance to a Nano S Plus

Essentially, a Nano S Plus can be rendered with a bunch of union, difference and intersection math operations. Here are the basic utilities I used:

```glsl
// SHAPE PRIMITIVES:
float sdCylinder( vec3 p, vec3 c ) {
  return length(p.xz-c.xy)-c.z;
}
float sdCappedCylinder( vec3 p, float h, float r ) {
  vec2 d = abs(vec2(length(p.xz),p.y)) - vec2(h,r);
  return min(max(d.x,d.y),0.0) + length(max(d,0.0));
}
float sdBox( vec3 p, vec3 b ) {
  vec3 q = abs(p) - b;
  return length(max(q,0.0)) + min(max(q.x,max(q.y,q.z)),0.0);
}
float sdBox2(in vec2 p, in vec2 b) {
  vec2 d = abs(p) - b;
  return length(max(d, vec2(0))) + min(max(d.x, d.y), 0.0);
}
float sdBoxRoundZ(vec3 p, vec3 b, float r) {
  return max(sdBox2(p.xy, b.xy-r)-r, abs(p.z)-b.z);
}
// SHAPE OPERATIONS:
float fOpUnionRound(float a, float b, float r) {
  vec2 u = max(vec2(r - a,r - b), vec2(0));
  return max(r, min (a, b)) - length(u);
}
float fOpIntersectionRound(float a, float b, float r) {
  vec2 u = max(vec2(r + a,r + b), vec2(0));
  return min(-r, max (a, b)) + length(u);
}
float fOpDifferenceRound (float a, float b, float r) {
  return fOpIntersectionRound(a, -b, r);
}
float opSmoothSubtraction( float d1, float d2, float k ) {
  float h = clamp( 0.5 - 0.5*(d2+d1)/k, 0.0, 1.0 );
  return mix( d2, -d1, h ) + k*h*(1.0-h);
}
void pR(inout vec2 p, float a) {
  p = cos(a)*p + sin(a)*vec2(p.y, -p.x);
}
```

This code might seems complex, but it's relatively simple primitives, some are from this great article: https://iquilezles.org/www/articles/distfunctions/distfunctions.htm


With these utilities, I have developed that function called `sdLedgerNanoSPlus`, that implements the **distance to a Nano S Plus**:

`HIT sdLedgerNanoSPlus (vec3 p, float rot)`

Knowing the "space distance to an object" allows to use a raymarching algorithm to render it in 3D.

The function takes two parameters `p` and `rot`:
- `p` is the 3D point from which to evaluate the distance. If the Nano S Plus is at 1 meter away from the Nano S Plus, it must return a value of 1 meter. as simple as this.
- `rot` allows for me to control the rotation of the swivel, so it can be animated from the caller.

The function returns one `HIT` value. `HIT` is a simple alias to `vec2`, which actually allows me to return a tuple of two values: `(distance, material)`. On top of the distance, I need to track what is the "closest material". Basically answering the question: from the point `p` what is the part of the Nano S Plus that is the closest? For instance, the swivel, the plastic part, the screen,...

> I was able to take precise measurements from some wireframes of the actual device and tried to make it as close as possible, transposed into code.


This is probably a lot of code to digest, but here is its implementation:

```glsl
HIT sdLedgerNanoSPlus (vec3 p, float rot) {
  float btn = sdBoxRoundZ(
    vec3(abs(p.x - 0.18) - 0.22, p.z, p.y - 0.155),
    vec3(0.06, 0.03, 0.04), 0.03);
  float case2d = sdBox2(p.xy, vec2(0.624, 0.174)-0.08)-0.08;
  float swivel_hook = sdCylinder(p.xzy, vec3(-0.44, 0.0, 0.074));
  HIT s = HIT(max(
    min(
      opSmoothSubtraction(
		    min(
          max(case2d+0.015, abs(p.z+0.12)-0.015), // main casing carving
          btn-0.004 // btns carving
        ),
        max(case2d, abs(p.z)-0.101) - 0.01, // main casing
        0.008
      ),
      min(
        btn,
        max(swivel_hook-0.015, abs(p.z)-0.12) // plastic in the casing for the swivel
      )
    ),
    -swivel_hook // carve the swivel hook out
  ), 2.05);
  // screen
  float screen2 = sdBox2(p.xy - vec2(0.18, 0.), vec2(0.27, 0.12));
  s = opU(s, HIT(max(s.x, screen2), 2.1));
  // swivel
  p.x += 0.04;
  p.x += 0.4;
  pR(p.xy, rot);
  p.x -= 0.4;
  float w = 0.54;
  float x = p.x + 0.8;
  float z = abs(p.z) - 0.12;
  float swivel_radius = 0.192;
  float swivel_metal_width = 0.006;
  float rounding = 0.003;
  float swivel = opSmoothSubtraction(
    sdCylinder(p.xzy, vec3(-0.4, 0.0, 0.08)), // carved
    min(
      sdCappedCylinder(vec3(p.y, z, x - 0.4), swivel_radius, swivel_metal_width),
      sdBox(vec3(x - 0.41 + w, p.y, z), vec3(w, swivel_radius, swivel_metal_width))
    )-rounding,
    0.04
  );
  // metal to close the swivel end
  swivel = fOpUnionRound(swivel,
    sdBox(vec3(x + 0.135 + w, p.y, p.z), vec3(swivel_metal_width, swivel_radius, 0.123))
  ,0.01);
  noiseMetal = fbm(vec2(40.0, 1000.) * p.xy);
  vec2 coord = fract(vec2(1.0, -3.0) * p.xy + vec2(0.5));
  vec4 mt = texture2D(metalText, coord);
  float t = mix(0., grayscale(mt.rgb),mt.a * step(p.z, 0.) * step(p.x, -0.5) * step(abs(p.y), 0.16));
  float swivelM = 2.2 + t;
  s = opU(s, HIT(swivel, swivelM));
  return s;
}
```

To visualize it more, I've animated the code to make it show the different steps union and difference operations:

<video muted loop autoplay controls src="/images/2021/12/gnsp/model.mp4" width="100%"></video>

But let's try to dive into more details and tricks.

### The main casing

The first part of the function is making the plastic casing:

```glsl
float btn = sdBoxRoundZ(
  vec3(abs(p.x - 0.18) - 0.22, p.z, p.y - 0.155),
  vec3(0.06, 0.03, 0.04), 0.03);
float case2d = sdBox2(p.xy, vec2(0.624, 0.174)-0.08)-0.08;
float swivel_hook = sdCylinder(p.xzy, vec3(-0.44, 0.0, 0.074));
HIT s = HIT(max(
  min(
    opSmoothSubtraction(
      min(
        max(case2d+0.015, abs(p.z+0.12)-0.015), // main casing carving
        btn-0.004 // btns carving
      ),
      max(case2d, abs(p.z)-0.101) - 0.01, // main casing
      0.008
    ),
    min(
      btn, // buttons themself
      max(swivel_hook-0.015, abs(p.z)-0.12) // plastic in the casing for the swivel
    )
  ),
  -swivel_hook // carve the swivel hook out
), 2.05);
```

We can see that I use a lot of `min()` to combine the primitives. when you apply `min(A,B)` between the distance of objects A and B it is essentially the distance to the union of A and B, because min returns the closest distance. so `min` is an union.

We can also see the use of many `max()` like for instance `max(case2d, abs(p.z)-0.101) - 0.01` which renders a rounded box but with sharp edge on the Z axis:

![](/images/2021/12/gnsp/casing.png)

> `max(A, B)` is basically the intersection of A and B. Sadly, it's not an "exact" distance that limits the ability to bevel a tiny bit the edge. If someone have a trick to implement this shape with the exact distance, I would love to know.

`max(case2d, abs(p.z)-0.101) - 0.01` is therefore made of the intersection of:
- `case2d` is a 2D box in xy space. defined by `sdBox2(p.xy, vec2(0.624, 0.174)-0.08)-0.08`. The value 0.8 is removed from the box dimension but also then removed from the distance. That value is actually the border radius of the box.
- `abs(p.z)` is the distance to the Z plan. `abs(p.z)-0.101` is distance to a volume of the plan enlarged with a `0.101` padding.

### Carving out

![](/images/2021/12/gnsp/casingdig.png)

The first operation done on the casing is to carve the part of the buttons and the inside. This is essentially done with the operation `max(A, -B)` (remove B from A), except here we are using a smooth difference operation to not make too "sharp" cuts.

The same technique is used on the swivel hole:

![](/images/2021/12/gnsp/casingdig2.png)

And again done on the model swivel shape:

![](/images/2021/12/gnsp/swiveldig.png)

**but for the swivel, it is done with a "smoothing difference"**, which creates the nice rounded effect in the hole:

![](/images/2021/12/gnsp/swiveldigresult.png)

Here is the code that do this:

```glsl
opSmoothSubtraction(
  sdCylinder(p.xzy, vec3(-0.4, 0.0, 0.08)), // the carving shape is a cylinder
  min(
    sdCappedCylinder(vec3(p.y, z, x - 0.4), swivel_radius, swivel_metal_width), // circle of the swivel
    sdBox(vec3(x - 0.41 + w, p.y, z), vec3(w, swivel_radius, swivel_metal_width)) // long rectangle metal part
  )-rounding, // add a bit of rounding (bevel)
  0.04
)
```

and if we tweak that 0.04 value between 0.0 and 0.1, we obtain this interesting range of smoothing subtraction:

<video muted loop autoplay controls src="/images/2021/12/gnsp/smoothdiff.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/smoothdiff2.mp4" width="50%"></video>

There would be so much to improve in the modelization. For instance, I couldn't figure out a simple way to make the smooth corner of the swivel metal, so I end up with this simplification which isn't perfect:

![](/images/2021/12/gnsp/modelsimpl.png)

```glsl
// metal to close the swivel end
swivel = fOpUnionRound(swivel,
  sdBox(vec3(x + 0.135 + w, p.y, p.z), vec3(swivel_metal_width, swivel_radius, 0.123))
,0.01);
```

Distance function can always be optimized and details can always be added, possibilities are infinite it's only a matter of how much hours do you want to spend on. And on my case, it was basically a weekend.


## Lighting and material

There would be a lot to write about the accumulation of techniques used for the lightning. Basically there are 2-3 lights in the scene and some are casting some shadows using raymarching as well.

<video muted loop autoplay controls src="/images/2021/12/gnsp/material.mp4" width="100%"></video>

*That video looks surprisingly so professional, I love it!* The scene is just this code:

```glsl
HIT map (vec3 p) {
  HIT s = HIT(10. - length(p), 0.);
  s = opU(s, HIT(length(p)-0.5, 2.05)); // sphere distance is just length(p)-radius
  return s;
}
```

It shows the rendering of a sphere on the plastic material. Before I talk about the materials, let's focus on the lighting.

### The lighting

The general code that renders the scene is pretty straightforward:

```glsl
vec3 scene(vec2 uv) {
  vec3 c = vec3(0.); // color of the pixel to set
  vec3 p = cameraP;
  vec3 dir = normalize(vec3(uv - .5, 1.)); // perspective camera
  dir = lookAt(cameraP, focusP) * dir; // camera focus on a point
  HIT hit = marcher(p, dir); // this throw camera ray and tells what points it hits (material and distance)
  vec3 n = normal(p); // this calculates the NORMAL VECTOR on the surface of the hit object
  c += lighting(hit, p, n, dir); // <= THIS IS WHERE LIGHTING IS CALCULATED
  c = mix(c, sceneBgColor, pow(smoothstep(4., 10., length(p-cameraP)), .5)); // mist on far away objects
  return c;
}
```

Ok, so as you can see on the previous video, we have essentially 2 lights in the scene, one blueish and one redish. They spread differently in the material to simulate a bit their different size. We however can see the user of a THIRD light, which is more in the back and will be useful to simulate the fact the background is emitting its color. This was very useful for strong background colors like orange:

<video muted loop autoplay controls src="/images/2021/12/gnsp/100.mp4" width="100%"></video>

This is what lighting is implementing:

```glsl
vec3 lighting (HIT hit, vec3 p, vec3 n, vec3 dir) { // (code is a bit simplified from original)
  vec3 l, ldir;
  vec3 c = vec3(0.);
  l = vec3(lightPos, 1.5, -3.4);
  vec3 obj = shade(hit, p);
  ldir = normalize(l - p);
  c +=
  0.92 * vec3(0.9, 0.7, 0.6) * (
    // ambient
    0.1
    // diffuse
    + obj
      * (.5 + .5 * diffuse(p, n, l)) // half lambert
      * (0.5 + 0.5 * softshadow(p, ldir, 0.05, 5., 8.))
    + specular(n, p, hit.y, ldir, dir, 10.)
  );
  l = vec3(-lightPos, 5., -2.);
  ldir = normalize(l - p);
  c +=
  0.92 * vec3(0.3, 0.5, 0.6) * (
  // ambient
  0.1
  // diffuse
  + obj
    * (.5 + .5 * diffuse(p, n, l)) // half lambert
  + specular(n, p, hit.y, ldir, dir, 20.)
  );

  l = vec3(0., 2., 8.);
  ldir = normalize(l - p);
  c += bgLightColor * (
    obj
    * diffuse(p, n, l)
    + specular(n, p, hit.y, ldir, dir, 20.)
  );
  return c;
}
```

You can see the first thing done here is:

```
  vec3 obj = shade(hit, p);
```

It is a very important step that ask the hit object material "give me your color". I will cover it in the Material section.

Then for each light I want to apply, you can see the same pattern:

First of all, we will put the light at a specific position in the space. For instance:

```glsl
l = vec3(lightPos, 1.5, -3.4);
```

we calculate the actual light direction with `p` which is the point of interest to color.

```glsl
ldir = normalize(l - p);
```

And then we can finally add to the object its emitted color:

```glsl
  c +=
  0.92 * vec3(0.9, 0.7, 0.6) * (
    // ambient
    0.1
    // diffuse
    + obj
      * (.5 + .5 * diffuse(p, n, l)) // half lambert
      * (0.5 + 0.5 * softshadow(p, ldir, 0.05, 5., 8.))
    + specular(n, p, hit.y, ldir, dir, 10.)
  );
```

and there are a few components that is very inspired by the classical "ambient diffuse specular" paradigm: https://learnopengl.com/Lighting/Basic-Lighting which I recommend you to read if you want to dive more into this part.

In my case, I use half lambert technique which I find really interesting for a cartoon-ish effect https://developer.valvesoftware.com/wiki/Half_Lambert and because i don't use expensive ambient occlusion.

I also, in this light case, will use `softshadow` that cast a shadow toward the light direction.

**specular** function is an important utility that have this implementation:

```glsl
float specular (vec3 n, vec3 pos, float m, vec3 ldir, vec3 dir, float p) {
  return specularStrength(m, n, pos) * pow(max(dot(dir, reflect(ldir, n)), 0.0), p);
}
```

note that we can have different "specular strength" for each material or even depending on the position.

### The material `specularStrength()`

<video muted loop autoplay controls src="/images/2021/12/gnsp/material.mp4" width="100%"></video>

As we can see in this material, the plastic has been added some texturing.

This is implemented with a fbm noise and it is contained in the material value.

Then I had two possible ways to make it visible: either I change the color of the material OR I change the way it reflect lights in `specularStrength`. I've used the second option for the plastic case:

```glsl
float noiseMetal;
float specularStrength (float m, vec3 n, vec3 p) {
  if (m < 2.1) {
  	float v =
  	  n.z * fbm(600. * p.xy) +
  	  n.x * fbm(600. * p.yz) +
  	  n.y * fbm(600. * p.xz);
  	return 0.4 + 0.3 * v;
  }
  if (m < 2.2) {
    return 2.0;
  }
  if (m < 4.) {
    return 0.6 - 0.5 * noiseMetal + 1. * ceil(m-2.21);
  }
  return 0.4;
}
```

So pretty basic stuff, I use `m` material value, which is a one dimension value to express all materials in. in plastic case, we are in the `m < 2.1` case which have a strong noise frequency.

On the same principle, we can see it is also done for the swivel metal.

I used some trickery here because, as the swivel is moving, I had to use a global variable to set the noise value because I don't have the "local position", only the global position.

The `noiseMetal` is set directly from the `sdLedgerNanoSPlus` function with this:

```glsl
noiseMetal = fbm(vec2(40.0, 1000.) * p.xy);
```

where `p` is a local position of the swivel, contextual to the rotation applied to it.

The 40/1000 implements a stretched fbm noise which nicely recreates the effect:

![](/images/2021/12/gnsp/metaltexture.jpg)


### The material `shade()`

`shade(hit,p)` is essentially the material coloring function. It tells what color does the object reflect at a given hit position.

Here is its implementation for the whole scene (I have omitted some part that will be covered in other articles):

```glsl
vec3 shade (HIT hit, vec3 p) {
  if (hit.y < 2.0) return sceneBgColor;
  if (hit.y < 4.0) {
    if (hit.y < 2.1) {
    	return plasticColor;
    }
    if (hit.y < 2.2) {
      return ...SCREEN RENDERING HERE...;
    }
    // swivel metal
    return vec3(0.7 - 0.1 * noiseMetal - 0.2 * (hit.y - 2.2));
  }
  if (hit.y < 5.0) {
    return stickerColor;
  }
  return vec3(0.0);
}
```

So it's a simple, "give me the color of the material id number". The only trick for the noise metal was to make it a bit darker on some part to accentuate the metal effect.

**The next article is going to dive into what this `...SCREEN RENDERING HERE...` part is doing, and more generally how I managed to also make the screen display text from inside a shader!**

This second article (in a series of 7 articles) reveals the technique used to 3D render the Generative Nano S Plus collection: using a GLSL fragment shader, without any 3D model, but with raymarching distance function technique.

GNSP – the 3D distance to a Nano S Plus



This article is the first of a series of 7 articles that will explain the development and release of GNSP – a special NFT collection I've been secretly working on for a Christmas gift offered to my colleagues at Ledger. It has been a wonderful year between my crypto-developer work and my crypto-artist work and this collection is here to celebrate it.

**Timeline:**

- [**article 1: GNSP – the concept**](/2021/12/gnsp)
- [article 2: the 3D distance to a Nano S Plus](/2021/12/gnsp-raymarching)
- [article 3: the nano screen](/2022/02/gnsp-nanoscreen)
- [article 4: the swivel](/2022/02/gnsp-swivel)
- article 5: the background
- article 6: the video generation
- article 7: the final drop
- (?March) public mint

<video muted loop autoplay controls src="/images/2021/12/gnsp/1558.mp4" width="50%" style="float:left; margin-right: 20px; margin-bottom:20px"></video>

The NFT collection is called "GNSP" which stands for "Generative Nano S Plus". The Nano S Plus is the new incoming device that Ledger will release next year, it was [announced at Ledger Op3n a few weeks ago](https://www.youtube.com/watch?v=qUVkfPwSdyg&list=PL6VM0N695IhkMNEvBAOoLeKLU05qDNfd5).



The NFT collection is pushed on Polygon (Ethereum Layer-2) and will have in total **2048 items** – one is unique for each word in [the standard BIP39 wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt). A dedicated contract was developed that allowed to do an internal airdrop but will later allow to open for a public mint phase. Right now, there are 233 mints done and owned by many of us but later, there will be 2048 items fully available! There are many diversity in this **generative art work**. Nothing has been developed "statically" everything is random and generative.

<br style="clear:left"/>

**The collection is browsable on https://greweb.me/gnsp**

The collection is also browsable on https://opensea.io/collection/gnsp but again, is only partial as not all the items are yet minted in the [contract](https://polygonscan.com/address/0x3c11b1975c17fcf8cbb315d4430233ed1e87cf05). The current plan is to release the public mintability in a near future – please stay tuned in case this plan changes.

## Why this collection?

First of all, I would like to say that I've been working on this secretly on my own artistic time to drop this as a great surprise for all my colleagues. These are not "NFTs made by Ledger" but I had great feedback and help from some colleagues in the team. I did this because i'm passionate but also because there is something valuable and important:

As an engineer working at Ledger for the past 4 years, it's sad to see how undervalued and forgotten are the security aspects of crypto-currencies in the NFT world. I have seen so many tutorials "how to get into NFT" that don't even mention the use of hardware wallets, and sadly we already have seen many hacks due to the use of software wallets not backed by a hardware wallets. The collection is an interesting way to convey this message – making it an NFT collection actively make everyone at Ledger learning more about owning NFTs and how it works under the hood as this is still a very bleeding edge technology! Your Ethereum address is your identify, your NFT collection is your digital persona, you better want it secured.

## real-time, model-less 3D raymarching

The 3D rendering is rendered in real time, in a GLSL fragment shader, without any 3D model, using raymarching distance function technique. Even tho a high quality video is attached to each of the NFTs and stored on IPFS, the source code is fully public [here](https://github.com/gre/gre/tree/master/doodles/generative-nano-s-plus) and it only needs an index to entirely render with just code, it is self hosted on https://greweb.me/gnsp/0. The 2048 series is finalized, it's not a secret and there are no "reveal" because its code is immutable.

More explanation of the rendering technique used will be explained in further articles.

## rarity, randomless and likelyhood

It's important to understand I didn't design the outcome of the actual collection, I have only designed the likelyhood of things to happen. For instance, I have designed that there is a 2 out of 2048 of chance that one of the item have a "Snoop Dogg" on the Swivel metal engraved part but when the dice was thrown, only one item happened to have the trait: https://greweb.me/gnsp/547.

<img width="50%" src="/images/2021/12/gnsp/547.png" />

The designed likelyhood of probability of things to occured have driven the final outcome of the rarity of all the traits. They will be fully available when everything has been minted. Note that the contract distribute the items randomly on-chain on each mint action so even I can't control who gets what. In other words, the collection is deterministically finished and fully discoverable as of today but it is getting distributed pseudo-randomly.

There are a lot of traits to discover, here is a few highlights. There are reference to some of my past work. There are many different kind of animations of the camera, swivel and screen.

<video muted loop autoplay controls src="/images/2021/12/gnsp/419.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/100.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/710.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/1300.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/1353.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/494.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/1170.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/1047.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/1231.mp4" width="50%"></video><video muted loop autoplay controls src="/images/2021/12/gnsp/260.mp4" width="50%"></video>

Some articles will cover more of these.

## Development eXperience set up and code architecture

The first PoC of this artwork was developed in one day, directly inside Google Chrome using the integrated IDE that lives under the Dev Tools: Did you know you can edit and save code from there? I have just used this, I did not use any compiler / webpack / babel but instead, I have directly used web modules and the `.mjs` extension. Unfortunately, I still needed an http server (that just hosts a folder) because `file://` doesn't allow web modules.

![](/images/2021/12/gnsp/dx.jpg)

The code was decoupled in modules to allow to split the logic, rendering, and execution code:

- **the logic part**: [`features.mjs`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/features.mjs) have all the likelihood logic that generates all the parameters and "features" for the art.
  - also some utilities: [`rng.mjs`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/rng.mjs) and [`perlin.mjs`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/perlin.mjs) that implement all the noise utilities.
  - it allowed me to run some statistics script to tweak my likelihood.
- **the render part**: [`art.mjs`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/art.mjs) takes in input the features/parameters to render the actual art.
- **the execution part**:
  - [`index.html`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/index.html) file that put everything together for web. It's using module import, also also import the only dependency I have: [regl](https://github.com/regl-project/regl/).
  - [`node.mjs`](https://github.com/gre/gre/blob/master/doodles/generative-nano-s-plus/node.mjs) implements headless Node rendering of the art, using headless-gl and node-canvas. It worked smoothly but I will explain this part more in *article 6* especially on why this ended up not being a so good idea for performance and what other alternatives I used.


This article is the first of a series of 7 articles that will explain the development and release of GNSP – a special NFT collection I've been secretly working on for a Christmas gift offered to my colleagues at Ledger. It has been a wonderful year between my crypto-developer work and my crypto-artist work and this collection is here to celebrates it.

GNSP – the concept

[plotnft]: https://greweb.me/plots/nft
[fxhash]: https://www.fxhash.xyz/u/greweb

**=> https://www.fxhash.xyz/u/greweb <= is where you can find my plottable generators.**

I plan to release a plottable generator every Wednesday – this article covers today's release & share some thoughts on how to approach generative art variety.


**Last week highlight:**

<img width="40%" src="/images/2021/11/plottablestorm/digital.jpg" style="float: left">

[See article to explain this concept](/2021/11/plottable-storm) released last week with "Plottable Storm" from which I learned and grew some ideas for the next iterations!
Plottable Storm may still be available on https://www.fxhash.xyz/generative/1050 – it was released via a mint of 10tez, which was pretty expensive for the platform's current price average – but made sense as the first "plottable NFT" of the platform. Note that, getting a physical plot is only an option, on which I will ask (1) to own the NFT and (2) to pay extra fees for me to plot it on demand.

<br style="clear:both">

## 🎉 Release: Plottable Mountain Moons

Ok, this may be the best plot generator I have ever created so far. I have put so much effort. This is months of iterations and experiments concentrated into one generator. I had goosebumps exploring the results and plotting them. This is just an illegal amount of fun.

I have also improved the ink simulating shader and added animation to make it visually interesting on its digital rendered version. Here is a quick preview:

<video loop autoPlay muted src="/images/2021/12/plottable-mountain-moons/promo1.mp4"  width="100%"></video>

**Find it on => https://www.fxhash.xyz/u/greweb <=**

## Tips: Prototype, prototype, prototype

I've developed my generator in the mind that it would be realistic to plot with fountain pens, e.g. without destroying the paper. This means I had to test a bunch of prototypes to check that:
- Paper can handle it (think of it like "load testing" but with ink)
- It's good looking (ink need to react well, some ink mix can be bad looking for instance)
- that the digital preview and the ink simulation is accurate (I've added many new inks and I had to tweak colors)

Here are a few prototypes I did this weekend... Actually 18 plots! Beware I use that as an iteration loop, so some helped to tweak things and do not necessarily represent a possible outcome anymore, but it's mostly the case.

<img width="100%" src="/images/2021/12/plottable-mountain-moons/all.jpg">

Each plot is done on a 21 by 21 centimeters watercolor paper.

Here are a few zooms:

<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom1.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom2.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom3.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom4.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom5.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom6.jpg">
<img width="100%" src="/images/2021/12/plottable-mountain-moons/zoom7.jpg">

And finally, the OG one that is the generator cover:

<img width="100%" src="/images/2021/12/plottable-mountain-moons/plot.jpg">


## Economy: Supply and Price

Determining the supply and price to put an NFT generator has never been easy. In fxhash, there is a great average of price of 0.5tez to 2tez which is very cheap if you think about what is happening in Ethereum. In a way, it needs to fit in this platform range, but I also need to think a lot about the supply: to me, the supply is proportional to the variety of your generator, how different results it can produce. Low Supply creates scarcity while High Supply gives more chance to collectors and reduce the FOMO effect. The price is also a way to limit the number someone can take, but is not very fair for low budget,...

For my case, and it may only justify for my own plans. I fallback-ed a bit on the idea (at least this time) to make is a Low Supply.

I decided this time to make it high in supply and a relatively accessible price for these reasons:

- This generator covers a great amount of my plotting work this year. A lot of primitives and shape combination has been converged into one big generator. And I find it fair and ethical that I can't anymore in the future release new generators that overlap too much with these. So in a way, this is a sacrifice to make. That means, I better need the supply to be high enough to make the generator fully express its variety.
- The idea of this NFT, first of all which are pretty cool as digital art, is also to use them as a power to have a physical action: claiming a physical plot to be performed. That physical plot request costs a fee. (currently set at 15tez but may evolve depending on demand and my capacity to respond to it) That means I want the price of the NFT itself to be relatively accessible which means low, which means supply need to have a better offer to those who will want to find the rare gems.
- I want my collectors to fully embrace collecting for the art and lower the "collecting for the speculation". Increasing the supply will decrease the scarcity effect that exist on second market. That said, it's not that high supply (smolskull was 2000!) and there will be room for second market to occur for those who are looking for "the perfect plot to perform".

## Tech: In pursuit of the perfect rarity equilibrium

My plot generator are develop with Rust. I have developed myself my own set of tools and I will basically have a watch loop that recompile and regenerate a .svg each time I change code. My Visual Studio Code set up will have a SVG display within the IDE while I can edit the generative code. This makes a nice ~5s live reloading development loop. Not bad.

The problem of this is that it's a generator, it yields a lot of different results. So I usually would just have a "seed" parameter exposed on the CLI and generate a folder with tons of images. Not very practical neither.

This time was still a bit of this for the initial development. But at some point I have to really think about the rarity of the results and trying to make everything interesting and unique. on my JavaScript side, I have a `generateVariables(random)` function that takes a RNG and yield a bunch of parameters to give to my generator as well as all the "features" to put in the NFT metadata.

### rarity analysis

This was really useful to split this in a dedicated file, because I could then develop a small node script that would do an analysis on 100 000 tries and give me stats about rarity. For instance:

```
Ink Sherwood Green
                     undefined: 95.2%
                      Mountain: 2.1%
                         Stars: 2.1%
                          Both: 0.6%
Inks Count
                             2: 71.7%
                             1: 28.3%
Mountains 2-Colors
                            No: 80.6%
                           Yes: 19.4%
Mountains Visibility
                           Low: 46.7%
                          High: 34.8%
                          Full: 10.8%
                         Empty: 7.7%
```

Which is super useful to try to classify and adjust how much you want a given case to occur. Indeed it forces you to really think about your classification first.

### as a query language

Ok, now what's super cool about this is I have a way to query my generator to give me a result of a given query!! So I made it work. Here are few examples:

```
node script.mjs 'p["Primitives"] > 4 && p["Inks Count"]==2'
ooa7qfERP3s73oycm7hvvtexuidFMvHtcr6dcLRHSpM9Uz33gVt
...
node script.mjs '(p["Ink Aurora Borealis"] && p["Ink Poppy Red"]) && p["Primitives"]>4 && o.a1 > 0.5 && o.f1 > 0.02 && p["Elements Count"]=="Normal" && p["Mountains Visibility"]=="Low"'
ooAzT5R8UgCy7eFYbvtryykBt8AVVBf25MQG7eknVfzHstahomV
```

the query is literally JavaScript code. And here is the simple script to run it:

```js
const predicate = new Function("p,o", "return (" + (argv2 || "true") + ")");
let r, hash;
do {
  const { fxhash, random } = newRandom();
  r = generateVariables(random);
  hash = fxhash;
} while(!predicate(r.props, r.opts));
console.log(hash);
```

### generating the .svg files in a folder

I didn't plan to explain in depth my tech stack because it would deserve a whole article, but to summarize: **generator is developed in Rust language, compiled in WASM which takes props and outputs SVG, which is rendered with WebGL shaders (sorry for your headaches)**

WASM can run in a web browser and is pretty efficient. (I'm not sure you can say the same of p5js for instance)

What's cool is WASM can also run in Node.js. So putting together that `generateVariables(random)` and even the query system, I ended up with a very powerful tool.

For instance, here I could generate a lot of results that have Blue Mountain and either Yellow or Pink moons:

```
node script.mjs '(p["Ink Amber"] || p["Ink Pink"]) && p["Ink Bloody Brexit"]=="Mountain"'
```

<img width="100%" src="/images/2021/12/plottable-mountain-moons/folder.jpg">

Pretty cool hey!

and the JavaScript is faily simple evolution of the previous code:

```js
const wasmBuffer = fs.readFileSync(path.join(__dirname, "./rust/pkg/main_bg.wasm"));
const wasmLoad = import("./rust/pkg/main.mjs");
wasmLoad.then(async (wasmModule) => {
  await wasmModule.default(wasmBuffer);
  const predicate = new Function("p,o", "return (" + (argv2 || "true") + ")");
  let r, hash;
  while (true) {
    const { fxhash, random } = newRandom();
    r = generateVariables(random);
    hash = fxhash;
    if (predicate(r.props, r.opts)) {
      const svg = wasmModule.render(r.opts);
      fs.writeFileSync("dist/" + hash + ".svg", svg, "utf-8");
    }
  }
})
```

I will definitely reuse this idea in the future. **With powerful tools comes great responsibilities!**


I plan to release a plottable generator every Wednesday – this article covers today's release & share some thoughts on how to approach generative art variety.

“Plottable Mountain Moons” and an approach to query generative art

[plotnft]: https://greweb.me/plots/nft
[fxhash]: https://www.fxhash.xyz/generative/1050


## The "Plottable NFT" paradigm

I've finalized what will be my paradigm for the next weeks and months:

- I will release a digital version of my work using NFTs and notably generative art NFT platforms.
- I will allow the NFT owners to request a physical plot on demand. ([https://greweb.me/plots/nft][plotnft])

### A collaborative and open ecosystem

The NFT, like any regular NFT, points to a digital artwork that can be sold and resold on second market – blockchain guarantees its unicity.

In the "Plottable NFT", such **NFT gives a privilege to its owner: requesting a physical plot** (with an artistic fee to cover costs, [see /plots/nft][plotnft]). This obviously can be executed multiple times, yet every physical piece is unique: plotting is an analog process that will inevitably yield different results.

[https://greweb.me/plots/nft][plotnft] sets my own "plotting services" terms but any other plotter artist is welcome to collaborate and contribute to offering to the community their own services under their own terms and interpretation of the art – I would just ask to verify that the requester owns the NFT.

<img width="100%" src="/images/2021/11/plottablestorm/schema.png">

The NFT vs physical art decoupling allows a business model that allows both the digital creator and the physical creator to be rewarded and makes the NFT truly interesting as a token that has a real-life action: to unlock physical pieces.

> You can be your own artist too, buy a plotter, try it out! This is all designed to be open-source friendly and you can download the SVG yourself!

## @greweb's generative art, plotting and NFTs

### RELEASING "Plottable Storm" on fxhash.xyz

[**=> Check my profile on fxhash.xyz <=**][fxhash]

**Here is one digital ink simulated version: (this is not a photo!)**

<img width="100%" src="/images/2021/11/plottablestorm/digital.jpg">

**Here is the physically plotted version: (photo of the 3 hours long plot on A4 paper)**

<img width="100%" src="/images/2021/11/plottablestorm/physical.jpg">


This work is based on one of my original exploration: [https://greweb.me/plots/312](https://greweb.me/plots/312).

> Plottable Storm is a flow field simulating fountain pen ink drawing on paper on its digital form. 10 inks, many rarity features varying noise, size and color positionning. Having only one color is rare.
> The digital NFTs can be used to perform a physical action: @greweb plotting on demand a fountain pen plot for those who also want physical originals.
>
> Digital and Physical art, hybrid and decoupled:
> - The art is made as a regular digital NFT on Tezos blockchain – its digital form rendered with WebGL shaders.
> - Token to the physical world: owning each NFT confer the power to request the related physical plot.
> 
> A collaborative and open ecosystem: an SVG file can be downloaded (Drag&Drop or right-click save) and plotted with fountain pens physically by plotter artists who can interpret it the way they want in their own conditions. @greweb offers his service on https://greweb.me/plots/nft
> 
> Designed for A4 size. Estimated time of 3 hours of plotting time (25% speed)


**Here are a few other physical plots made during the exploration**, especially important to tweak the generator to make a plot that would be feasible without damaging the paper too much!

<img width="100%" src="/images/2021/11/plottablestorm/2.jpg">
<img width="100%" src="/images/2021/11/plottablestorm/3.jpg">
<img width="100%" src="/images/2021/11/plottablestorm/4.jpg">

### Coming from past explorations

This latest work is a continuation of a lot of previous explorations. In the past months, I've been continuously exploring different ways to combine physical art with digital NFT and one of the recent way I've been trying this is ["Pattern 03" (article)](/2021/08/pattern-03).

I've been polishing my ink simulator lately and based on the same principle I will be able to generate more plots and have easy ways to iterate on. The tech stack is a bit ambitious, experimental and unique:

- The SVG generator is implemented in Rust language and then compiled and executed in WASM on the browser.
- It is rendered in real time and enhanced with WebGL shaders.

In context of [Ethereum absured fees](https://etherscan.io/gastracker), I've decided to focus my NFT effort on other blockchains like Tezos. I'm also focusing even more on my "plottable art" lately because, even if it's maybe not where I find the most sucess, it is definitely what I love the most experimenting with. There are so much challenge to tackle with the physical ink and paper constraints.

### Future plans

This year, I've been releasing a plot a day as shown on [https://greweb.me/plots](https://greweb.me/plots) and I intend to continue to do so, but in a more organized way:

**On the next weeks, and on a weekly basis,** I intend to release a new plottable NFT generator on fxhash. "Plottable Storm" is hopefully the series of many! I will adapt some of my best plotting explorations of this year but I also plan to dedicate time on exploring new ideas.

**Starting next year, on a monthly basis,** I intend to have a "subscribe to my plots" series where people would receive surprise plots in their mailbox from me and using a NFT membership system. The idea is still a work in progress – **Would you be interested in this idea? Don't hesitate to keep in touch with me if you like this concept.**


I will release a digital version of my work using NFTs and notably generative art NFT platforms. I will allow the NFT owners to request a physical plot on demand.

“Plottable Storm”, a generator of plottable SVGs


This weekend, a new platform called fxhash emerged on https://fxhash.xyz/, which opens to everyone the release of NFT art generators – similar to artblocks.io but on the Tezos blockchain.

This platform have a lot of hicetnunc's vibe when it was released back in March: it is very experimental yet a huge community is jumping into it – this was long awaited on Tezos. It is trustless and fully opened like hicetnunc was. Despite being in a beta state, there is already a decent UX and DX (developer experience): The developer onboarding might be one of the best among all the generative art platform I've been able to test. Without contacting anyone, I was able to publish my first generator. You get guided interactively and end to end from testing your generator, snapshotting the preview and signing transactions to publish it. It is completely trustless and autonomous.

**Beware the platform is still barely working due to heavy load from the community trying to jump into it.**

This weekend, I released a variant of one of my "shaderday" to make "Wave":

> Wave by @greweb – https://www.fxhash.xyz/generative/67
>
> <video src="/images/2021/11/duality/wave.mp4" width="60%" controls autoplay muted loop></video>

I will now release a new generator called 'Duality' – heavily inspired from https://greweb.me/shaderday/65 but with a lot of variety of results and loop possible.

## Duality

will appear soon on https://www.fxhash.xyz/u/greweb

> Duality is a minimalistic loop of circles and squares jumping between dark and light sides. wide variety of effects using repetitions, polar modulus, disc and squares. There are very rare cases implemented that may be revealed over mints! A generalization of my "Jumping Blob" creation – develop in 2021 under water by @greweb.

<video controls autoplay muted loop width="100%" src="/images/2021/11/duality/a.mp4"></video>
<video controls autoplay muted loop width="50%" src="/images/2021/11/duality/b.mp4"></video><video controls autoplay muted loop width="50%" src="/images/2021/11/duality/c.mp4"></video>
<video controls autoplay muted loop width="50%" src="/images/2021/11/duality/d.mp4"></video><video controls autoplay muted loop width="50%" src="/images/2021/11/duality/e.mp4"></video>
<video controls autoplay muted loop width="50%" src="/images/2021/11/duality/f.mp4"></video><video controls autoplay muted loop width="50%" src="/images/2021/11/duality/g.mp4"></video>
<video controls autoplay muted loop width="50%" src="/images/2021/11/duality/h.mp4"></video><video controls autoplay muted loop width="50%" src="/images/2021/11/duality/i.mp4"></video>


fxhash: duality


- [Pre-release article](/2021/08/pattern-03)
- [Post article: Part 1: covering the rarity aspects](/2021/08/the-day-after-pattern-03)
- [Post article: Part 2: covering the future plots](/2021/08/plotting-pattern-03)

> 🤗 **The ethblock.art BlockStyle ['Pattern 03'](https://ethblock.art/style/32) sold out yesterday in only 2 hours with 888 pieces.** I still can't believe it. There are no words to describe how thankful I am for all your support. THANK YOU!

You can browse through the mints on [https://ethblock.art/style/32](https://ethblock.art/style/32).

As a first disclaimer, I will have to say it's nearly impossible to cover in this article all of the 888 or even to classify them, there are amazing discoveries. I will highlight some of them.

## Rarity in ethblock.art

With ethblock.art there is always a search for the rare piece. This happens because everyone wants to find the pearl that no one will have, the one that will be unique among them all. Nevertheless, the rarity often appears where no one expected. There is also a bit of game theory at play here: if everyone mints the same rarity, it's not reeeaaally rare anymore in the final collection. What makes a great piece ultimately is the general composition and the (relative) beauty of the piece. I would always recommend not necessarily to search for the "rarity by design" (by the BlockStyle creator rules) but to find something that you like with all these components at play.

In the case of 'Pattern 03', some very cool patterns emerged. Symmetry plays an important role to reveal it, like in Nature.

The metadata of OpenSea are still loading as we speak but I'm going to highlight a small analysis of what happened with some of the picks to explain it.

## Designed rarity of Pattern 03

There were a few elements that were covered yesterday (check the [Pre-release article](/2021/08/pattern-03)) and that took an important part yesterday.

### Crosshatch shape

This shape has been used relatively popularly as it's quite rare.

Here are many examples:


[*#6824 BY BITSIKKA.ETH* ![](/images/2021/08/picks/6824.png)](https://ethblock.art/view/6824)
[*#6739 BY 0X8A53...63CF* ![](/images/2021/08/picks/6739.png)](https://ethblock.art/view/6739)
[*#6813 BY 0XE20A...866E* ![](/images/2021/08/picks/6813.png)](https://ethblock.art/view/6813)
[*#6807 BY J0RDAN.ETH* ![](/images/2021/08/picks/6807.png)](https://ethblock.art/view/6807)
[*#6931 BY SETANIMALS.ETH* ![](/images/2021/08/picks/6931.png)](https://ethblock.art/view/6931)
[*#6611 BY KLEINTONNO.ETH* ![](/images/2021/08/picks/6611.png)](https://ethblock.art/view/6611)

### The symmetry

Symmetry helped a lot on revealing some human / animals patterns and let me highlight some.

[*#6991 BY 0X5A17...4A17* ![](/images/2021/08/picks/6991.png)](https://ethblock.art/view/6991)
[*#6958 BY 0XB84D...04D3* ![](/images/2021/08/picks/6958.png)](https://ethblock.art/view/6958)
[*#6766 BY BITSIKKA.ETH* ![](/images/2021/08/picks/6766.png)](https://ethblock.art/view/6766)
[*#6776 BY 0XB8BA...F556* ![](/images/2021/08/picks/6776.png)](https://ethblock.art/view/6776)
[*#6778 BY 0X27F8...269B* ![](/images/2021/08/picks/6778.png)](https://ethblock.art/view/6778)
[*#6766 BY BITSIKKA.ETH* ![](/images/2021/08/picks/6766.png)](https://ethblock.art/view/6766)
[*#7154 BY 0X2D55...8034* ![](/images/2021/08/picks/7154.png)](https://ethblock.art/view/7154)
[*#6808 BY 0X3037...CF6E* ![](/images/2021/08/picks/6808.png)](https://ethblock.art/view/6808)
[*#6817 BY 0XE63E...1D85* ![](/images/2021/08/picks/6817.png)](https://ethblock.art/view/6817)

### inks used

As I expected, black was the most common ink used. It's pretty good to get nice contrasts, especially on important patterns.

Black is 25% of plots, then comes "Bloody Brexit" ink which is a dark blue (about 10%). then the great "Red Dragon" which is a strong red (about 8%). Then indigo and turquoise take about 5% each.

I don't have precise stats because OpenSea is still indexing.

### colors-duality

About 20% of the picks are using two colors so it was an undeniable search from minters.

I was very interested by the combination of colors that were chosen, some I had never considered in the past and it truely was a revelation to me on some ink coupling to try more in future.

[*#6824 BY BITSIKKA.ETH* ![](/images/2021/08/picks/6815.png)](https://ethblock.art/view/6815)

[*#7000 BY PLAYPAUSESTOP.ETH* ![](/images/2021/08/picks/7000.png)](https://ethblock.art/view/7000)

[*#7013 BY 0X81E5...5D63* ![](/images/2021/08/picks/7013.png)](https://ethblock.art/view/7013)

[*#6790 BY 0XB8BA...F556* ![](/images/2021/08/picks/6790.png)](https://ethblock.art/view/6790)

[*#6832 BY 0X42AD...B84E* ![](/images/2021/08/picks/6832.png)](https://ethblock.art/view/6832)

[*#7030 BY 0X6E82...918E* ![](/images/2021/08/picks/7030.png)](https://ethblock.art/view/7030)

[*#6637 BY 0XB8BA...F556* ![](/images/2021/08/picks/6637.png)](https://ethblock.art/view/6637)

## Undocumented rarity of Pattern 03

There were a few surprises that I didn't document but that some of you found out!

### "partial" lines

Another dimension of the "colors duality" is actually to have the second color not plotted at all, it makes it back to one color but with part of the pattern that is simply disabled.

It's about as rare as having a dual color. And it was used by a few pieces.

**it allowed to keep only one line here:**

[*#6777 BY 0X44DC...F3BD* ![](/images/2021/08/picks/6777.png)](https://ethblock.art/view/6777)
[*#6736 BY 0X04C4...A644* ![](/images/2021/08/picks/6736.png)](https://ethblock.art/view/6736)

there are many other examples of "partial" lines.

### The "strikethrough" lines.

I've made it possible that on top of borders, there would be some strikethrough lines. It was both a really rare feature and also very hard to use properly in a way that it's really estetic. It allows to "divide" the space of the canvas.

Here are technically all the possible strikethrough:

<img src="/images/2021/08/strikethrough.jpg" width="400"/>

Here is a prototype plot that shows how lines blends:

<img src="/images/2021/08/strikethrough-pic.jpg" width="400"/>

It's not easy to "simulate" in the digital version and be 1:1 with the physical result because all the parameters at stake with the fountain pen, ink and paper.

Technically, the SVG have a lot of lines that goes back and forth to achieve this:

<img src="/images/2021/08/strikethrough-spec.png" width="800"/>

One of the mint:

[*#6979 BY 0XBA29...0345* ![](/images/2021/08/picks/6979.png)](https://ethblock.art/view/6979)

### Ink saturation

One of the important feature I developed was to try to simulate the effect of important amount of ink. This is something you can see at stake in https://mountainofink.com/blog/diamine-pink which is one of the ink I use.

Here are 3 examples:

[*#6802 BY 0X04C4...A644* ![](/images/2021/08/picks/6802.png)](https://ethblock.art/view/6802)
[*#6804 BY 0XAE68...FBE3* ![](/images/2021/08/picks/6804.png)](https://ethblock.art/view/6804)
[*#6800 BY 0XE20A...866E* ![](/images/2021/08/picks/6800.png)](https://ethblock.art/view/6800)

that last one will be particularly interesting to plot because of the "red-ish" effect of that ink.

### Curly loops: a rarity that wasn't found! (correct me if i'm wrong)

There were a rare possibility that the displacement would have been so high that it would have make lines curly.

This was in the prototype:

<img src="/images/2021/08/picks/curly.png" width="400"/>

I have to admit this property is pushing the plotting to a certain extreme because small curls often will be too hard for the paper and the pen will start digging through it. So i'm relief 50% of the plots are not like this. 😅

## Organic rarity

There are rarity aspects that happened organically and that I didn't planned or anticipate at all. That is the beauty of generative art in general. It goes beyond its creator.

### low/stable `f` noise values

(refer to [first article](/2021/08/pattern-03) for explanation of `f`)

While there were indeed a possibility for the `f` value to go low or having a very similar value, I didn't anticipate it would be used as a feature and having other factors (e.g. `displacement`)

So these art appear to not have `f` noises at all:

(fun fact, this block was minted [3 times!](https://opensea.io/collection/blockart?search[stringTraits][0][name]=BlockNumber&search[stringTraits][0][values][0]=13115508))
[*#7025 BY 0X91D7...28B3* ![](/images/2021/08/picks/7025.png)](https://ethblock.art/view/7025)

as well as this one which nearly have no `f` but have an heavy cos displacement and a pattern I never expected:

[*#7182 BY 0X7DB2...E04B* ![](/images/2021/08/picks/7182.png)](https://ethblock.art/view/7182)

There are a few similar pieces having these wavy displacement

[*#7193 BY 0X9422...17DF* ![](/images/2021/08/picks/7193.png)](https://ethblock.art/view/7193)
[*#6938 BY ZEROLIGHTING.ETH* ![](/images/2021/08/picks/6938.png)](https://ethblock.art/view/6938)

### Great usage of the "radial gradient"

One uncommon feature of the generator was to create concentric circles. It can happen either by "removing" or by "adding" into the `f` factor. It was curated in various interesting ways.

[*#7049 BY PSYCHOKILLER.ETH* ![](/images/2021/08/picks/7049.png)](https://ethblock.art/view/7049)
[*#7042 BY GABRIELLEMIC.ETH* ![](/images/2021/08/picks/7042.png)](https://ethblock.art/view/7042)
[*#7178 BY PBOCK.ETH* ![](/images/2021/08/picks/7178.png)](https://ethblock.art/view/7178)
[*#6714 BY 0XE20A...866E* ![](/images/2021/08/picks/6714.png)](https://ethblock.art/view/6714)

### Pushing the plots to their extreme

I'm not astonished that some mints pushed the generator to its extreme boundaries but some of the picks still surprised me.

**very low line resolution (mod5) with white holes:**

[*#7056 BY 0XBA29...0345* ![](/images/2021/08/picks/7056.png)](https://ethblock.art/view/7056)

**extreme displacement and f going beyond 1.0 (so it overlaps the next line)**

[*#7040 BY 0XD21A...100C* ![](/images/2021/08/picks/7040.png)](https://ethblock.art/view/7040)

**one liner**

[*#7151 BY 0X5AB4...BAD5* ![](/images/2021/08/picks/7151.png)](https://ethblock.art/view/7151)

**invisible art** (which funnily I tried to prevent but you still found one!)

[*#6900 BY 0X81E5...5D63* ![](/images/2021/08/picks/6900.png)](https://ethblock.art/view/6900)

**extreme amount of lines**

[*#6640 BY 0X8A53...63CF* ![](/images/2021/08/picks/6640.png)](https://ethblock.art/view/6640)


**A LOT OF OTHER COOL THINGS! impossible to cover everything.**

[Next article on the future plots](/2021/08/plotting-pattern-03)



The ethblock.art BlockStyle 'Pattern 03' sold out yesterday in only 2 hours with 888 pieces. The day after Pattern 03, covering the rarity aspects.

The day after Pattern 03 (1/2)


- [Pre-release article](/2021/08/pattern-03)
- [Post article: Part 1: covering the rarity aspects](/2021/08/the-day-after-pattern-03)
- [Post article: Part 2: covering the future plots](/2021/08/plotting-pattern-03)


> 🤗 **The claiming phase has ended. Please now refer to https://greweb.me/plots/nft if you want a physical plot.**

## What about the physical art?

Quick recap of the philosophy announced before the BlockStyle was released:

**Decoupling physical art from its digital form:** Not all digital NFT collectors also are physical collectors. It is therefore important to allow both to co-exist without having a limitation on any side.

**Openness and scalability of physical plotting**. The digital NFT have a "SVG" button on hover which allow to download the SVG file (right click, download). The SVG format is a vectorial format that is used to define all the "paths" of drawing. It is the recipe to plots. That way, this is truly scalable and decentralized. Like blockchain is. I am not necessarily the only one that can plot the work physically. It could be you. It could be another artist. This model allows it.

**An economy around the digital NFTs?**  In this decoupled model, 'Pattern 03' digital NFT are the main pivot NFTs at stake. an economy can be built around them. Physical artists can plot them, create & sell on side collection that allows the second market to grow. There are many ways this can be traded: for instance swapping the digital NFT as a currency is a possibility that would be recommended, but so is doing a more regular "selling print as a service"... Ultimately, the physical artist value their own skills, own "touch" – a bit like a baker can sell baguettes with a shared recipe designed by ancestors.

## *"@greweb 'Pattern 03' plots"* collection

A collection [*"@greweb 'Pattern 03' plots"*](https://opensea.io/collection/greweb-pattern-03-plots) has been created on OpenSea.
It will curate plots that I will start drawing in the coming days.

It's going to be a time-consuming process as a plot takes about 1 hour to perform (depending on settings and complexity of the lines). The physical art is designed to be plotted with fountain pens on A4 water-colour 300g paper and then cut into a 21 by 21 centimeters piece with a 5mm padding (so your art is a 20x20cm square). The planned inks to use are those described by the "Ink" trait (Diamine inks). The digital NFT has simulated a rendering that will be relatively well respected. There is going to be unpredictability when plotting it for real.

> Disclaimer: Beware I will likely not be able to plot them all. There are 888 items and it takes an average 1 hour to plot. However, I'll start plotting following a bit this curation decision process:
> - personal favorite picks
> - I will look at Opensea most starred NFTs
> - I will look at Opensea most sold NFTs
> - also if you really want the physical piece. e.g. if you ask me on Discord / Twitter. I can sure take request and add it in the wished list But I can't guarantee it as it would probably takes me 800 hours =)

## [EXPIRED] First phase: 🎉 claim a physical plot *before November 1st, 2021*

This first phase will ends on November 1st, 2021 for all physical NFTs. The presented offer will only be available during that time. The NFT physical I own after this time will still be owned by me and a second phase will be documented later.

**How did it work?**

You can claim a physical NFT (created on the collection shared above) **as long as you own the digital NFT**. 

To claim it, you make a small Offer on the NFT physical (pay what you want, e.g. 0.03 WETH – ideally >0.02 to cover the mint cost) so I can verify you are the NFT digital owner & proceed to the NFT transfer of that 'physical NFT'.

You will then get a code to obtain it physically.

**How shipping works?**
- The 'physical NFT', once acquires, will have unlockable content with instructions on how to contact me for proceeding to shipping.
- **IMPORTANT: Please use a PO Box or other postal service ( e.g. https://en.wikipedia.org/wiki/Poste_restante ). I do not want to know your home address, thanks.**
- On my side, I will use a simple (possibly tracked) letter to ship the 20x20cm art internationally.

## second phase

**The second phase is done via https://greweb.me/plots/nft**


<img width="50%" src="/images/2021/08/artist-1.jpg" /><img width="50%" src="/images/2021/08/artist-2.jpg" />


The ethblock.art BlockStyle 'Pattern 03' sold out yesterday in only 2 hours with 888 pieces. Let's cover what's next with future plots.

The day after Pattern 03 (2/2)


See follow-up articles:

- [Post article: Part 1: covering the rarity aspects](/2021/08/the-day-after-pattern-03)
- [Post article: Part 2: covering the future plots](/2021/08/plotting-pattern-03)

🤗 **The ethblock.art BlockStyle ['Pattern 03'](https://ethblock.art/style/32) was released on August 28th, 2021 and sold out in only 2 hours with 888 pieces.**

Pattern 03 is a tribute to fountain pen plotting, generating strokes lines to yield unique patterns. It recreates the condition of ink on paper in a digital art form. The second market will be exciting as these are also physically plottable. A SVG file can be downloaded from each NFT that is the recipe for a physical artist to perform the art physically (20cm square), with their own tools.

This article goes through many features of the generator and includes plotting tricks, technical notes, and useful information for collectors. You will see images attached, both digital and physical prototypes, at the end the rendering is very similar!

<img width="50%" src="/images/2021/08/pattern-03-post.jpg" /><img width="50%" src="/images/blockstyles/pattern-03/01.png" />

For many months, I've been exploring plotting art with fountain pens while exploring many different creative coding techniques. Every day, I've been releasing generators and plotting art that you can find on https://greweb.me/plots. This has been very interesting both technically and artistically. I expanded more and more my algorithm knowledge and creative coding techniques. These various experiences now contribute to this next level: I've made a "super generator" that generalizes many of them into one bundled *ethblock.art* BlockStyle generator.

Pattern 03 took a lot of patience and iterations to achieve its final result. I put my own expectation pretty high, I wanted great variety (and tweaking parameters is always hard). I also wanted a very realistic rendering technique that would almost look like the physical piece. The digital version had to be as good, if not better, than the possible physical piece that it could produce. I believe a lot in digital NFT by itself and the goal is to embrace digital-first.

In the past months, I've been thinking a lot about NFTs and the possibilities of physical VS digital art. I see many artists bridging the two worlds as well, there are many great experiments out there, I collected a bunch of physical art myself via NFTs. You already saw me already trying this ["plot loops"](/2021/05/plot-loops) concept.

**By minting on the generator, you are generating digital art.**

A lot of effort has been spent on the digital piece itself. It renders in a very realistic way on your browser, almost like if it was plotted, simulating many aspects of plotting. There is even a slight animation that I let you discover! The digital art is a unique 1:1 piece that will be an NFT that includes the SVG recipe:

 **By minting on the generator, you are curating one recipe for a possible plot.**

I've been plotting many prototypes to tweak parameters in a way that everything should technically be drawn with fountain pens! By minting, you are curating a plottable art that an artist from the plotting community could use. I've intentionally made it public and open for anyone to download the SVG related to a mint piece: ultimately anyone can plot it. This only unlocks the possibility and I will personally be one of this "physical artist" for the coming weeks. **(see *NFT and physical pieces?* section for more information)**

**By minting on the generator, you are a curator of the future plot collection.**

Giving the possibility for curators to select plotted art out of a generator with fine controls to tweak it is beyond anything I've seen done today in this field. In fine, minters have the responsibility to chose something really interesting that worth plotting, to express this responsibility, the fees to mint has been a bit higher than my previous BlockStyle.

 
 What I now want to achieve is to make the NFT as good "digitally" as it can be "physically". I've been plotting many prototypes to tweak parameters in a way that everything should technically be drawn with fountain pens! I want this art to be both physical and digital and in a loosely coupled way that gives full freedom of preferring one or the other or both.

 I intend later to offer a way for collectors to obtain the physical creation from me, but I believe this idea is beyond me and anyone in the plotting community could pick these to plot them. I believe a lot in free art, opensource and hacking mindset. I enjoy a lot free initiative like [plotterfiles.com](https://plotterfiles.com/) and this was a great inspiration here.

## What is EthBlock.art?

Before talking about 'Pattern 03', a quick recap of the platform I'm releasing on:

EthBlock.art aims to create a virtuous ecosystem of "deterministic art", code visualization of Ethereum blocks. Everything is data: from the ethereum block of transactions, to the code that visualizes it, and to the NFTs minted/traded using Ethereum transactions (that themselves are into Ethereum blocks).

This is a virtuous ecosystem, similar to [Supply Chain Transformation concepts](https://en.wikipedia.org/wiki/Value_chain): each actor in this ecosystem add value and get retributed for it, as I tried to explain in this schema:

![](/images/posts/cryptoaliens/ethblockart.png)

## The controls

As a minter, you get 6 "mods" controls.

- **MOD1:** allows you to pick your color. which recreates the conditions of some inks. Black is very powerful but also other inks are very vivid.

- **MOD2:** is controlling two factors, the border width (0.5 to 1.0) and the intensity of the noise (cycles twice).

- **MOD3:** is a general padding control and also tweaks border placement and sometimes lines distance.

- **MOD4:** control the alignment of waves and the amplitude of the "displacement" effect.

- **MOD5:** controls the resolution of each line. (beware high values slows down other mods)

- **MOD6:** adds a variable blur effect.

> MOD2 to MOD5 are controlling at least two properties of the art. This is something I like to call the "duality of controls". When you make one slider controlling two properties, you are giving a lot of variety while "constraining" the boundaries of the possible tweaks, forcing the minter to look for other blocks. This also is very important for the UX of the controls. There is always a tradeoff between being fully in control and having to search another block.

## Rarity features, block data and what drives the generation

In JavaScript is implemented the logic to extract out the "parameters" of the generator from the block data. While some of the work relies on the block hash and use an RNG (fun fact: there are 70 calls to `random()` to make it very diverse in results and rarity), some of the work also are big data analysis on the block data.

I'm going to document here how some of the main features work, You can do a general Ethereum blocks analysis to find the shape you prefer!

There are some other rarity features that I intentionally do not fully document. You do not need to "hunt" for the rarity that is "designed by the author", but instead search for the organic rarity & enjoy patterns and unexpected shapes.

> I crawled a lot of data from coingecko and etherscan to snapshot the prices of all ERC20 tokens in a way that I can value exactly how much a block have in $. I can then compare the Ethereum value and the ERC20 tokens value and do decisions based on it. (evaluated with Aug 2021 static prices)

### Main shapes

This most important feature split is the main shapes:

- If there is at least one transaction and mostly only Ethereum is transferred on that block (which is the case for very old blocks btw), you're going to get a **"rectangle spiral"**.
- If more $ is transferred in ETH than in ERC20 tokens, it's going to be **vertical lines**, **horizontal otherwise**.
- And finally, if there are actually exceptional amounts of ERC20 transfers (mostly only ERC20 transfers) it's going to Cross-Hatch.


### lines and "sub-lines"

**First: The plots are all composed of N main lines.**

The number of lines are driven by the number of transactions. More there are transactions in the minted art, more likely the number of lines will be high. This goes between 1 and 90 and these extremes are rare.

**Second: each line subdivide into M "sub-lines".**

It is most visible when there are not a lot of "lines" as it will diverge so much that sublines are no longer touching:

![](/images/2021/08/turquoise-crosshatch.jpg)

but it can also be subtle and not separate at all:

![](/images/2021/08/orange_lines.jpg)

### `f` main driver of curves

What I call `f` is a function that drives the sublines positioning and effectively makes them expanding or collapsing into one same line.

It is implemented using various noises and combined with different techniques. The following plot is covering most of them:

![](/images/2021/08/pink-osc.jpg)

- the general noise effect is the most common feature here and is available 99% of the time (not having this noise is rare). It is built with Simplex Noise and domain warping.
- the circling is an added feature that is not very common. It can have various properties.

There are also other cases like the fact lines would sometimes stop when the `f` values goes below 0.0.

### `displacement` second driver of curves

Displacement is a similar yet different technique. It allows displacing the whole lines independently of the `f` values. 

- The waving effect seen in the pink image above is produced with simple trigonometry.
- It can aggressively make lines moving a lot, even "looping" sometimes.

Displacement is overall a relatively rare feature. It is also one possible source of trouble for plotting (can dig the paper if you draw too much at the same place!) so it was pretty well contained.

Here is an example of displacement with aggressive settings:

![](/images/2021/08/aggressive-displacement.jpeg)

> It looks like a photo but this is actually the digital version!

### Inks and colors

The curator-artist chose one color among 11 inks. Each ink has various properties and some are very vivid. I would overall recommend black which produces very good contrast plots, but it's great to have the general possibility.

![](/images/2021/08/inks.jpg)

There are some plots that have color duality and that can also be plotted:

![](/images/2021/08/color-duality.jpg)

> This is a prototype and I was not careful as the corner and the final line scratch. Plotting is a challenge!

## Plot optimizations

A plotter is a machine that follows your drawing paths, here using SVG. When you do a SVG `<path>` every `move` (M) will be an actual move so you got to avoid useless moves. As it's easy to "move to the start" in algorithms, something that should not happen here.

Sometimes, the pen also was going up where I planned to "continue", this was the case of the initial algorithm of the "rectangle spiral", I avoided doing moves and preferred to connect lines.

To optimize the traveling of plotting lines, I've made it go back and forth: The first line is drawn from left to right, the second line gets drawn from right to left, and so on... This allows to avoid too much undesired ink accumulation or other pen/paper issues by alternating the direction.

Another problem I've optimized is the order of plotting lines and sublines. Instead of plotting all sublines in once, I preferred to plot the first subline of each line, then the second subline of each line, and so on... Despite the small extra move it requires, it's very important to balance the ink evenly as some inks tend to "dry" a bit over time which makes the drawing "fade away" as it flows. What's interesting is you can see the fading happening on each line:

![](/images/2021/08/strokes-zoom.jpg)

which is something I've simulated on the digital piece too! The effect varies from one ink to another.

> See also how the ink behaves on this photo? accumulation of this ink produces red-ish colors. Something that can be observed on the digital generator as well!

## Technical stack

Technically speaking, I believe this is the best achievement I did in a few years and profoundly refreshing. I managed to connect my creative coding pipeline: Rust generating SVG files, used through WASM and post-processed in WebGL to add extra effects and simulate the ink drawing. This was a blast to put these all together and I feel I've found something I'll keep doing in the next weeks and months.

The choice to use Rust was initially a personal exploration, using a language that is meant to be performant while being relatively high level and functional. It's something I did initially for plots and it helped on time-consuming algorithm. I've used it here for two reasons: first of all, most of my tooling for plotting is written in Rust, I'm very fluent it in now and I have many helpers I could reuse, secondly, there is a gain of performance. I have initially written my code in JavaScript and had some bad performance on the simple templating of the SVG code, I've estimated a gain of about x2 on the performance of using Rust. There are no super complex algorithms here, but it's still 2-3 loops with big iterations on them. The performance overall can still feel a bit slow, but you have to imagine each mod changes regenerate the SVG that can be up to 4 MB of XML.

I didn't try to enable asynchronicity or parallelism but it's something I will dig in the future when I'll do more complex work like shape packing (that can require parallelization).

This is a melting pot of technologies as I had to work on 3 aspects:
- In JavaScript is managed the logic that handles mods and block data and bakes the "parameters" of the generator.
- In Rust is implemented the generator itself, taking parameters in input and resulting SVG file.
- In WebGL/GLSL and gl-react library is implemented the simulation of ink on paper rendering.

## NFT and physical pieces?

The release of "Pattern 03" on EthBlock.art is primarily "digital" NFTs. Every BlockArt is going to be a digital NFT that includes the SVG recipe to make it physical.


**The physical collection is not meant to be 1 physical for 1 digital**. The idea is that the digital NFT remains unique but the physical art can be explored in different ways or ordered multiple times, it will not be guaranteed unique. Actually I can't prevent the plot to be done X times, like anyone can draw X times a La Joconde. However Nature have randomness and each physical plot will be unique.

**This is by design decoupled.**

- There are curators that prefer digital art, this is the BlockArt. There are curators that may be interest by the physical version.

- The "physical artist" do not necessarily need to be the same as the "digital artist". The idea here is the art goes beyond me, the digital pieces are recipes and a community of plotters could be using these digital pieces in different ways under different terms and with their own tools. This is the openness of blockchain and NFT and this is secured by the contracts and the ownership of NFTs.


**What I plan personally to do "as a physical artist"**. Now that this decoupling is explain, let me take the physical artist hat.
As physical plot have some cost, there are many ways to cover this. Indeed the simplest way is just to sell physical goods like a regular marchant.

As I said before *Nature have randomness and each physical plot will be unique.*. As a physical plot is still unique, I will emit an NFT each time I plot something.

In my case, there will be two ways of buying the physical piece:

- Either you will be able to SWAP your digital NFT against the physical NFT. And physical art will be shipped physically to where you want.
- Or you will be able to BUY it, but the price will be intentionally HIGHER than the digital NFT / will be following a bit the "floor price" of the digital NFTs of the collection.

I will also be the one to chose what I plot, I will not necessarily "plot them all" (but I can take requests) and I will not necessarily keep a 1:1 relationship as shared before. Actually, if you chose the SWAP option, I will have back the NFT digital, this is the way I get "paid" as I can then put it back on market.

I believe this ecosystem will be amazing and will allow a lot of options and freedom. I am so thrilled by the possibilities of NFT.

<img width="50%" src="/images/2021/08/artist-1.jpg" /><img width="50%" src="/images/2021/08/artist-2.jpg" />


Pattern 03 is a tribute to fountain pen plotting, generating strokes lines to yield unique patterns. It recreates the condition of ink on paper in a digital art form. The second market will be exciting as these are also physically plottable. A SVG file can be downloaded from each NFT that is the recipe for a physical artist to perform the art physically (20cm square), with their own tools.

Pattern 03, the first plottable generator on ethblock.art


<img width="400" src="/images/2021/05/relics.gif" />

# Releasing **Relics**, my first curated NFT collectible series, on Tezos blockchain and platform [_hicetnunc.xyz_](https://hic.link/greweb).

**Collection:** There are 28 curated visual loops that will be shared on the 7 days of this week. 4 NFT a day. I will use French day names as well as French seasons to name them all.

**Technical:** Relics collection are unique animation made with Perlin noise, cellular automaton and GLSL. The generator is fully open source and available on my website here: https://greweb.me/shaderday/63 as I strongly believe in open sourcing literally everything I do even as an artist. That said, I curated carefully the 28 unique NFTs myself and it's the only official collection of that generator.

> Contact me if you are the buyer to obtain the parameters of your NFT. Unfortunately it's not possible yet to "unlock" content as part of buying a NFT but I would be glad to give you the parameters of your NFT! I can also generate high resolution versions on demand (but also, the open sourced code allows it, once you have these parameters!).

_Lundi d'hiver, Lundi de printemps, Lundi d'été, Lundi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/61391"><img src="https://cloudflare-ipfs.com/ipfs/QmSbZ7iK1S2aDKtTM4HLkzjZrMCwgyDhNbqum8kQTfF44N" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/61403"><img src="https://cloudflare-ipfs.com/ipfs/QmbGrg2mckEbz5u6ShuQi5SbRcUKkEiY9S8irExUiJLizS" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/61410"><img src="https://cloudflare-ipfs.com/ipfs/QmZSQduPnXvmWvFo8JdC3WrxjzU9MbaKGD2JtywtWRq6C8" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/61413"><img src="https://cloudflare-ipfs.com/ipfs/Qmb2qS5Vp7YPfW5KqqgEm4aFqeTaGv2RXb81j1mG9dcLqL" width="25%"/></a>

_Mardi d'hiver, Mardi de printemps, Mardi d'été, Mardi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/63131"><img src="https://cloudflare-ipfs.com/ipfs/QmQHcBZ18wYDMq2B2i7AfQFC1e5CJytgsYxYzuanJ8Zxuy" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/63126"><img src="https://cloudflare-ipfs.com/ipfs/QmZRfP9fNKWRizNzHEiB4yHFPTSAuij53XJzXdeqz2qqNu" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/62848"><img src="https://cloudflare-ipfs.com/ipfs/QmT4xPg39PyVDEYGSi1BRce62jJnt2w8SmCDxEYJaZ47cQ" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/62839"><img src="https://cloudflare-ipfs.com/ipfs/QmXrWE4csSkPXYRg3BqhFmKVCzbXGDtNLRkku6Gc2PCY2Y" width="25%"/></a>

_Mercredi d'hiver, Mercredi de printemps, Mercredi d'été, Mercredi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/64885"><img src="https://cloudflare-ipfs.com/ipfs/QmcwpMrbg3n3iNo1TgQUS5LarKwFwz6kK9wexkc38ybRgT" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/64874"><img src="https://cloudflare-ipfs.com/ipfs/QmeDzVu5G1wLJxEsDXJXtdiJpMWAiRDfJnRgx16VmGH96X" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/64863"><img src="https://cloudflare-ipfs.com/ipfs/QmZuJcvNG2T7sCn959CWEuHZxi1C2Nr5H5JzbV6Sp5Pz3p" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/64852"><img src="https://cloudflare-ipfs.com/ipfs/Qmcomh1sD8L6wewENSWnqLT4akpRwrDpgABy8viu68b9Ua" width="25%"/></a>

_Jeudi d'hiver, Jeudi de printemps, Jeudi d'été, Jeudi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/66703"><img src="https://cloudflare-ipfs.com/ipfs/QmRe8RwPjLhatKbSMV5YGf3TDBKdB8W7xVnM8zQzNqe3dM" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/66686"><img src="https://cloudflare-ipfs.com/ipfs/QmNpPhofb4eJJq7YCDpjba8t3fNFQkY8W9ryM2iSreWkwB" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/66683"><img src="https://cloudflare-ipfs.com/ipfs/QmRN9L8PhKmfb4uM2LsFb2C2Gxa3YHZ7KQFZsSbSAUAMZ6" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/66674"><img src="https://cloudflare-ipfs.com/ipfs/QmXh2RAdgP841oJWdyMtBSQ78XnYQwHzEkTF8qze6hnbCn" width="25%"/></a>

_Vendredi d'hiver, Vendredi de printemps, Vendredi d'été, Vendredi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/68578"><img src="https://cloudflare-ipfs.com/ipfs/QmTXdtycdrp4v6UWymCeDJCamxHqUdHdy99XfK7vmVqqtx" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/68575"><img src="https://cloudflare-ipfs.com/ipfs/QmVyxcykCS8f1vpriReyedAfdP1M9wHq8pwyKtWtoUgXRb" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/68572"><img src="https://cloudflare-ipfs.com/ipfs/QmY1HcgrX7S5wxaYxRoFuxUWEdG6W6gAApDpzc1oYHSUDt" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/68522"><img src="https://cloudflare-ipfs.com/ipfs/QmSc8Q5ozk8nhLvzF6jry613WDhvFX6PjbqnKbyb97smhy" width="25%"/></a>

_Samedi d'hiver, Samedi de printemps, Samedi d'été, Samedi d'automne._

<a href="https://www.hicetnunc.xyz/objkt/69282"><img src="https://cloudflare-ipfs.com/ipfs/QmasrfTskgzSj48gG62xFyWvXrJXWznyPakMB7GtYwgcY3" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/69280"><img src="https://cloudflare-ipfs.com/ipfs/QmdvFEWzkbK2yPNSNURPNNJTkGf55MoDfboXboCvYwVUob" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/69276"><img src="https://cloudflare-ipfs.com/ipfs/QmZhD4pwmRB43CN7hXKouGHMgCdwuFfnBweJfNBeSJeTBt" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/69275"><img src="https://cloudflare-ipfs.com/ipfs/QmdgVW9CnMY1P6o41EEaiwsJMDQdgxhPzo4xmrV8YLLJ66" width="25%"/></a>

_Dimanche d'hiver, Dimanche de printemps, Dimanche d'été, Dimanche d'automne._

<a href="https://www.hicetnunc.xyz/objkt/70994"><img src="https://cloudflare-ipfs.com/ipfs/QmbTE4QGptyHGYsyemttEXSDoydapMuBiT94kooD3zLHc9" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/70991"><img src="https://cloudflare-ipfs.com/ipfs/QmXMUCZmptV4MyXJ8zUMM9ZoAfmWMLCTr5toPH99YLo6LY" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/70973"><img src="https://cloudflare-ipfs.com/ipfs/QmfVNN6bfzhsEK5fx45DwQTQ6hMrbASxgGzQnSgTwJEbJd" width="25%"/></a><a href="https://www.hicetnunc.xyz/objkt/70967"><img src="https://cloudflare-ipfs.com/ipfs/QmU1VEYV7zyyN3LhES4mgAm8qdgjgvDERDRqu7GJnKtVQL" width="25%"/></a>

_published on [hic.link/greweb](https://hic.link/greweb)_


Relics collection are unique animation made with Perlin noise, cellular automaton and GLSL.

Relics NFT collection


I am thrilled to release my first **"plot loop"** and plan to release one every week. Let me explain simply the idea:

- an animation is generated with code, (SVG plottable files)
- Each frame of this animation is plotted physically,
- photographed back into a digital picture,
- and post-processed back into a video that makes it an artistic creation by itself as well as each physical plot being one "edition" of that plot loop series.

> **You can see all my plot loops made so far at [https://greweb.me/plots/tags/plotloop](https://greweb.me/plots/tags/plotloop)**

**So there are two creations:**

- the animation is itself digital art => it is released as an NFT, with as many editions as there are frames.
- each individual frame is physical art => it can be shipped to first buyer.

### Plots and NFT ?!

**Plot loop animations will be released as [Non Fungible Token (NFT)](https://www.youtube.com/watch?v=Y-i9Jsm95ro)** on [hicetnunc](https://www.hicetnunc.xyz/). It allows anyone with Tezos crypto currency to acquire this video on Tezos blockchain. Digital collectors are collecting one edition of this NFT which adds to their collection: **The NFT video is an art in itself**. On top of this, physical collectors can also claim the shipping of the physical art of the frame corresponding to the collected NFT edition (there is as many editions as there are frames plotted).

**This is a hybrid concept between physical and digital art.** By buying a frame (by order of buy), the first buyer has the possibility to chose what happens to the physical art: either you allow me to keep it OR you can claim it (contact me on Twitter) and have me sending it anywhere in the world!

> I'm writing a bigger article about my recent NFT exploration and my art in general. I've been exploring so many ideas recently. I already sold some plots via NFTs, I am very honored to have found some buyers 😍. They can still be found at [hic.link/greweb](https://hic.link/greweb). I'm currently burning them one after the other to expire the possibility to buy them as I will focus on these new projects.

## First release, the triplanet loop

**hicetnunc NFT: [OBJKT#57902](https://www.hicetnunc.xyz/objkt/57902)**

<a href="/plots/121"><img width="50% " src="/images/plots/121.gif"/></a>

My first plot loop is called "Triplanet". It's a transition of two parametric functions with many perlin noise displacements. This is a continuation of ["Planet Holes"](/plots/100) series as well as recent ["Parametric stack"](/plots/111) explorations.
Every frame is generated with a Rust script I wrote.

**Triplanet was released in [plots#121](/plots/121).** 16 frames have been plotted with fountain pen on bristol paper (ink: Red Dragon by Diamine).

<img width="100%" src="/images/plots/121_walled.jpg"/>
<img width="50%" src="/images/plots/121_zoom.jpg"/><img width="50%" src="/images/plots/121_plot.jpg"/>

**Plotting with fountain pen is challenging** as it requires many search on the ink, paper and many fail and retry. Plotting all these frames took an afternoon.

## What's next?

I plan to release a _plot loop_ every week.

It's taking a lot of time to plot all frames so there are great challenges: first of all is to reduce the number of frames, secondly is to make them worth it, to make them really good: I want every frame to be unique, to include some specific elements, easter eggs, that make it recognizable out of the other frames.

---

# Please also check out other great artists

I believe a lot of this hybrid idea of mixing plot, animation, and NFTs. It was very funny for me to see all coïncidence and convergence of ideas on this topic. It's one of these moments when we have the same ideas at the same time. I'm not the only one exploring this and I want to do a big kudos to these great artists.

### Marion [@atelier_marion](https://twitter.com/atelier_marion/status/1388071908575490048)

who recently released a very similar idea! <del>She has 2 more frames yet to be taken!</del> Not anymore!

<a href="https://www.hicetnunc.xyz/objkt/42546"><img src="https://cloudflare-ipfs.com/ipfs/QmXcAWQTaGHQp4BGy1krER284PoaPCNhKYzDrxp86MaM7b" style="max-width: 300px"></a>

She is also creating impressive drawing work as seen on her website: https://www.marionguy.com/shop

### Maks Surguy [@msurguy](https://twitter.com/msurguy)

who is behind [plotterfiles.com](https://plotterfiles.com/) platform. He also does a lot of great plotting art and thought about similar concept recently! [Checkout this article about his work.](https://medium.com/poptwig/artist-in-focus-maks-surguy-26277c95b197)

### Thomas Lin Pedersen [@thomasp85](https://twitter.com/thomasp85)

who is doing a [stuning work](https://www.hicetnunc.xyz/tz/tz2Pkj2xWJovKKCsABjnr3NbyMVJTMBkpTvb) and very impressive landscapes. Also selling NFT for shipping physical print.

He recently did a very cool NFT in collaboration with **Lionel Radisson** [@MAKIO135](https://twitter.com/MAKIO135):

<a href="https://www.hicetnunc.xyz/objkt/53662"><video style="max-width: 300px" controls autoplay loop src="https://ipfs.io/ipfs/QmaGfhSgWX1UTq6jPX11mfHDxccK5eXGYqi6u71zNLaBhY"/></a>

### ...so many other artists!

Let's chat! You can join us on [hicetnunc's discord](https://discord.gg/jKNy6PynPK) on channel #phygital-objkts which explore very similar idea and where other artists will be active!

I'm also available for collaboration.


Releasing my first 'plot loop', generative animation plotted and published as an NFT.

'Plot loops' concept


[main]: /2021/04/cryptoaliens

> See also [CryptoAliens: Genesis][main] main article.

This article explains how [CryptoAliens: Genesis (ethblock.art)][main] works in technical depth.

<img src="/images/posts/cryptoaliens/032_px.png" width="50%" /><img src="/images/posts/cryptoaliens/036_px.png" width="50%" />

First of all, I would like to point out the [source code is available here on Github](https://github.com/gre/gre/tree/master/blockarts/CryptoAliens).

This whole idea was kicked off on [Twitch](https://twitch.tv/greweb). A recording is [available on Youtube](https://www.youtube.com/watch?v=WUzOlLq0IAo). Apart from the many glitches this 3 hours session had remained to be solved, the main part of this was implemented that night. Indeed I had to work countlessly on polishing the shaders, lighting and post-processing. I also spent a lot of time using the block data in a meaningful way because it's what [EthBlock.art](https://ethblock.art) really is about.

## EthBlock.art revolutionary idea

Before going further into the technical details of CryptoAliens, I would like to point out how revolutionary this EthBlock.art idea is.

The project aims to create a virtuous ecosystem of "deterministic art", code visualization of Ethereum blocks. Everything is data: from the ethereum block of transactions, to the code that visualize it, and to the NFTs minted/traded using Ethereum transactions (that themselves are into Ethereum blocks).

**This is a virtuous ecosystem, similar to [Supply Chain Transformation concepts](https://en.wikipedia.org/wiki/Value_chain): each actor in this ecosystem add value and get retributed for it, as I tried to explain in this schema:**

![](/images/posts/cryptoaliens/ethblockart.png)

`CryptoAliens: Genesis` is one possible BlockStyle that I've designed, as a creative coder. It tries to visualize what happened in the Ethereum Block and will take mods into account to try to be as good as possible to deliver interesting possibilities to BlockArt minters.

## Ok, so how is it implemented technically?

Indeed WebGL.

More precisely, it is implemented with [`gl-react`](https://github.com/gre/gl-react) which is convenient to write and compose [_GLSL Fragment Shaders_](https://www.khronos.org/opengl/wiki/Fragment_Shader).

**here is the big picture of the pipeline:**

<video src="/images/posts/cryptoaliens/graph.mp4" width="100%" controls autoplay muted loop></video>

There are 2 main shaders: Mandelglitch (for skin texturing) and Scene (the main raymarching shader). Each of them take a bunch of parameters. `mod1..4` are values from the creator. The rest are inferred from the Block information, they are split into multiple parameters for convenience.

The parameters `s1..9` are coming directly from `mersenne-twister` library, a [PRNG](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) used to get a wide and deterministic variety of shapes, initialized with the block hash. That said, as pointed in the previous section, the main features of the shape are determined by Ethereum block information itself (number of transactions, timestamp, transfers, gas used,...).

On top of these, some other parameters are controling key elements they come from more block information (heavy, head, bonesK, arms info,...).

The technique implemented on the main Scene shader is [raymarching distance functions](https://www.iquilezles.org/www/articles/raymarchingdf/raymarchingdf.htm). The shapes at stake are mostly segments that are merged with a smooth union. There are many loops involved which made it challenging to optimize.
There may be issues on some mobile phone even tho it works on mine thanks to a "pixelated" version. (downscaling the pixels helped)

Because of an heavy usage of this technique, the main scene was really challenging to optimize, it actually runs something like 5 FPS. My choice was to not animate it directly (you can see on the rendering graph that actually the buffer don't need to refresh, except when a "mod" is changed). However, thanks to intermediary framebuffers we can do 60 FPS animation at the postprocessing level. This is what the final user will get as the mods are static.

### Canvas 2D to draw texts

A Canvas 2D element is used to draw the text that will appear on top of everything.

```js
/// canvas used to draw in postprocessing ///
function FrameText({ blockNumber, dateText, width, height, kg, bones }) {
  const onCanvasRef = (canvas) => {
    if (!canvas) return;
    const ctx = canvas.getContext("2d");
    const w = ctx.canvas.width;
    const h = ctx.canvas.height;
    const pad = Math.round(w * 0.01);
    const padX = Math.round(w * 0.02);
    const fontS = Math.floor(0.19 * w) / 10;
    const fontSize = `${fontS}px`;
    ctx.save();
    ctx.fillStyle = "#000";
    ctx.fillRect(0, 0, w, h);
    ctx.font = "bold " + fontSize + " monospace";
    ctx.textBaseline = "top";
    ctx.fillStyle = "#fff";
    ctx.fillText(`CryptoAliens specimen #${blockNumber}`, padX, pad);
    ctx.textBaseline = "bottom";
    ctx.textAlign = "right";
    ctx.font = fontSize + " monospace";
    ctx.fillText(
      `born ${dateText}, ${kg} kg, ${bones} bones`,
      w - padX,
      h - pad
    );
    ctx.restore();
  };
  return (
    <canvas
      ref={onCanvasRef}
      width={String(width * 2)}
      height={String(height * 2)}
    />
  );
}
const FrameTextCached = React.memo(FrameText);
```

### How is Mandelglitch used?

As said, [Mandelglitch BlockStyle](https://ethblock.art/create/17) is re-used in this CryptoAliens BlockStyle. This really is the power of gl-react: it makes such composability really easy to do, the same way you can compose React components.

You can see in the [Youtube recording](https://www.youtube.com/watch?v=WUzOlLq0IAo) the way I have implemented it initially: it is just a simple import of Mandelglitch.js (literally the BlockStyle as-is) that I can just send as a uniform sampler2D.

```
<Node
  shader={sceneShaders.scene}
  uniforms={{
    t: <Mandelglitch block={block} mod1={mod1} mod2={mod2} mod3={mod3} />,
  ...
```

after that, it was simpler to embed Mandelglitch in the BlockStyle.

The way Mandelglitch texturing is used however is that I will only use the "red" component and remap it to CryptoAliens' own palette, in order to have a better control of the coloring.

### Code organisation

React and Gl-React allows to organize the code relatively easily. First of all each pass in the rendering scene is a component, then shaders are organized in the `Shaders.create` usage. I've tried to collocate them (still in same one big file to simplify the upload to EthBlock.art).

I find it pretty convenient to externalize piece of the logic into "hooks" function. Example:

```js
const CustomStyle = (props) => {
  // prettier-ignore
  const { block, attributesRef, mod1, mod2, mod3, mod4, highQuality, width, height } = props;
  // prettier-ignore
  const { kg, bones, theme, background, s1, s2, s3, s4, s5, s6, s7, s8, heavy, head, bonesK, armsLen, armsSpread, armsCenter, armsEndW, dateText, blockNumber } =
    useBlockDerivedData(block, mod1, mod2, mod3, mod4);

  useAttributesSync(attributesRef, kg, bones, theme);

  return (
    <LiveTV
      text={
        <FrameTextCached ... />
      }
      ...
    >
      <NearestCopy width={w} height={h}>
        <Scene
          t={<MandelglitchCached ... />}
          ...
        />
      </NearestCopy>
    </LiveTV>
  );
};
```

`useBlockDerivedData` internally uses `useMemo` in order to cache the computation of block data interpretation.

In order to make **only** one part of the tree to actively re-render, i've used a local `useTime` that would re-render only that part (the LiveTV final shader). It's implementation is trivial:

```js
function useTime() {
  const [time, setTime] = useState(0);
  useEffect(() => {
    let startT;
    let h;
    function loop(t) {
      h = requestAnimationFrame(loop);
      if (!startT) startT = t;
      setTime((t - startT) / 1000);
    }
    h = requestAnimationFrame(loop);
    return () => cancelAnimationFrame(h);
  }, []);
  return time;
}
```

## Arms joints rotation, GLSL random and determinism

Ok, this is a hard topic. But it's extremely important that every BlockArt reliably produce the same result with the same block data, regardless of the computer used.

That last "regardless of computer used" part has challenged me at the last minute! JavaScript doesn't have this problem because it's stable between implementations (computers, engines). However, **this is not the case with OpenGL / GLSL**: every computer, every hardware (GPU) or possibly the "backend" implementation for WebGL ([ANGLE](https://github.com/google/angle) have different backends) can differ when it comes to float precision and primitive results.

In my shader, I was using the classical `random` function that is documented at https://thebookofshaders.com/10/

```cpp
float random (vec2 st) {
  return fract(sin(dot(st.xy, vec2(12.9898,78.233))) * 43758.5453123);
}
```

It works very well when you need a nice 2D distributed noise for basic effects **but it is very bad if you strongly rely on a stable & consistent noise to generate different shapes**.

Empirically, I can observe that `sin()` yields different results on different computers.

This was impacting me badly because I was able to see very various shapes:

<img src="/images/posts/cryptoaliens/rand1.png" width="33%"/><img src="/images/posts/cryptoaliens/rand2.png" width="33%"/><img src="/images/posts/cryptoaliens/rand3.png" width="33%"/>

What I need to varies a bit here is just the angle at each joint of the arms. This is very important for the uniqueness of the creature. The problem is that if each value changes a tiny bit, the whole thing diverge VERY QUICKLY, as the rotation angle will accumulate.

Worse than that, I had a bad pattern to accumulate randomness like this:

```cpp
float ss1 = s1;
for (int i = 0; i < armsLen; i++) {
  ss1 = random(ss1);
  ...
}
```

Actually I don't need that, first of all it's probably not good for performance, secondly I can just afford taking the fractional part of a simple polynomial:

```cpp
float arm (inout vec3 p, float index, float w, float h) {
  float s = sdSegment(p, h, w);
  float base1 = 305.53 * s1 + 77.21 * index;
  float base2 = 403.53 * s2 + 69.71 * index;
  for (int i = 0; i < armsLen; i++) {
    float fi = float(i);
    float ss1 = fract(base1 + 9.412 * fi);
    float ss2 = fract(base2 + 8.823 * fi);
    pR(p.xy, 8. * s4 * (ss2-.5));
    pR(p.xz, 6. * s5 * (ss1-.5));
    s = fOpUnionSoft(bonesK, s, sdSegment(p, h, w));
    h *= .9;
    w *= .9;
    p.y -= 1.2 * h;
  }
  s = fOpUnionSoft(bonesK + 0.2 * s5, s, length(p) - armsEndW);
  return s;
}
```

Note that here it's very arbitrary numbers, the point is to obtain variety and unpredictability in the results. `fract` is a very simple operation (take the fractional part of the number). Indeed i'm still prone to approximation, but the risk is limited by the fact i don't go too high in values here. Worse case scenario is it varies a bit the rotation but it should be so tiny that it won't be visible.

As said before and as seen in this code, the number will be used to do rotations (that `pR` is transforming `p` with some rotations). I use `s4` and `s5` values to give the magnitude of rotations.

**Let's look at a few cases:**

If both s4 and s5 are very near 0.0, it will be straight arms (it's a rare case therefore).

<img src="/images/posts/cryptoaliens/042_px.png" width="50%"/><img src="/images/posts/cryptoaliens/033_px.png" width="50%"/>

If one of the s4 or s5 are 0.0, it will be only happening on one "plan", or slightly diverging spirals, which I assume also to be rare cases:

<img src="/images/posts/cryptoaliens/017_px.png" width="50%"/><img src="/images/posts/cryptoaliens/020_px.png" width="50%"/>

Otherwise, most of the times, it will be relatively random:

<img src="/images/posts/cryptoaliens/029_px.png" width="50%"/><img src="/images/posts/cryptoaliens/032_px.png" width="50%"/>
<img src="/images/posts/cryptoaliens/028_px.png" width="50%"/><img src="/images/posts/cryptoaliens/026_px.png" width="50%"/>

## going 128px. Last minute decision, hard tradeoff

Due to concerns on the "deterministic rendering" from Ethblock.art folks, I had to make a choice regarding the fact it was too slow on mobile... I've decided to switch to 128x128 rendering for ALL platforms so it's consistent.

All the images on that article were done on 1024x1024 which is slow on computer and not even working on my mobile phone. (OnePlus)

It's hard to have efficient raymarching today when you have many items.

**Ultimately, I like how it finally looks, there were some minimalism / cell shaded styles,.. now it embraces Pixel Art even more!**

<img src="/images/posts/cryptoaliens/r02.png" width="50%" /><img src="/images/posts/cryptoaliens/r01.png" width="50%" />

It's also always possible to make higher quality version of these rendering and I'm excited to experiment more of these in future.

---

My name is greweb, and I'm a noise explorer. **feel free to ping me on Twitter [@greweb](https://twitter.com/greweb)**


Technical aspects of CryptoAliens digital creatures generated with Ethereum blockchain blocks. They can be minted on ethblock.at by anyone, which establishes a limited set of CryptoAliens species.

CryptoAliens: Genesis, a technical look


[create]: https://ethblock.art/create/24
[opensea]: https://opensea.io
[tech]: /2021/04/cryptoaliens-tech

> See also [CryptoAliens: Genesis, a technical look][tech].

<img src="/images/posts/cryptoaliens/021_px.png" width="50%" /><img src="/images/posts/cryptoaliens/001_px.png" width="50%" />

> CryptoAliens: Genesis establishes the first embryonic species. Which CryptoAliens are you going to chose? Each creature gets born on an Ethereum block that nourishes its shape: transactions, ETH value transferred, gas,... their unique skin comes from Mandelglitch's BlockStyle with the same rarity scheme.

## What are CryptoAliens?

CryptoAliens are digital creatures generated from Ethereum blockchain blocks. They can be minted on [ethblock.art][create] by anyone, to establishes a limited set of CryptoAliens species in a decentralized matter. Each block produced on Ethereum have unique elements that can be visualized in creative ways.

<img src="/images/posts/cryptoaliens/014_px.png" width="50%" /><img src="/images/posts/cryptoaliens/017_px.png" width="50%" />

> **CryptoAliens are born and nourished from transactions, transactions are bones, ETH is flesh,... and many other aspects that this article will explain!**

<img src="/images/posts/cryptoaliens/032_px.png" width="50%" /><img src="/images/posts/cryptoaliens/013_px.png" width="50%" />

### So I decide which ones are the CryptoAliens?

**Yes! As a NFT minter, you are the creator and you contribute at establishing the first 'Genesis' series of CryptoAliens.** You decide which creature deserve to live. You are the curator and it is your responsible to do a lot of research and find the most adorable (or the creepiest?) creature!

<img src="/images/posts/cryptoaliens/036_px.png" width="50%" /><img src="/images/posts/cryptoaliens/004_px.png" width="50%" />

### How many CryptoAliens are there?

Every single CryptoAliens species is unique and there are currently 12 millions because that's as many blocks there are today (April 2021). Every 15 seconds, a new block is minted on Ethereum blockchain (with usually hundreds of transactions in it) making a new CryptoAliens possibility.
The block is the DNA, but the creature only starts existing when minted!

**TLDR. CryptoAliens only comes to life when someone mint it as an NFT on the [ethblock.art][create] contract.** They can then be sold and traded on [opensea.io][opensea]. There is **a limited amount of CryptoAliens possible to mint** so be wise at your choice. In this 'Genesis' series, the current supply is set to 100!

<img src="/images/posts/cryptoaliens/002_px.png" width="50%" /><img src="/images/posts/cryptoaliens/003_px.png" width="50%" />

### What is 'Genesis' series about?

The idea of 'Genesis' is that we are collectively going to create the initial species of this universe (with the NFT we chose to mint).

Minting a _CryptoAliens: Genesis_ specimen is giving birth to the creature, therefore the current NFT is visualized on [ethblock.art][create] as a video tape recording of that time of birth (with the block number, time, weight and number of bones). These data are included in the NFT itself and could be reused in future!

## What determines how a CryptoAliens specimen looks like?

There are many information contains in Ethereum blocks that will get used to determine the general shape and gives its rarity.

### Block's timestamp

<img src="/images/posts/cryptoaliens/040_px.png" width="50%" /><img src="/images/posts/cryptoaliens/041_px.png" width="50%" />

When the block happened during UTC night, the visual will be in dark mode.

### Block's transactions amount

<img src="/images/posts/cryptoaliens/007_px.png" width="50%" /><img src="/images/posts/cryptoaliens/008_px.png" width="50%" />

When a block contains a lot of transactions it will impact its general weight. It will be highlighted by this very heavy blobs shapes. That said, the weight can be more or less dense based on amount of bones and also unique for each CryptoAliens specimen.

### Block's heavy transfers in ETH

<img src="/images/posts/cryptoaliens/035_px.png" width="50%" /><img src="/images/posts/cryptoaliens/020_px.png" width="50%" />

As said in the introduction, "ETH is flesh". Even tho most of the time it will impact the general weight of the creature, when a block contains an expectionally high transfer of Ethereum value, it will be highlighted by a big "head" on the creature. ("head" in doublequote because none of our scientist really figured what is this)

### Block's exceptionally low amount of ETH transferred

<img src="/images/posts/cryptoaliens/005_px.png" width="50%" /><img src="/images/posts/cryptoaliens/006_px.png" width="50%" />

On the contrary, when a block contains almost no ETH transfers, the arms will be very thin. Clearly ETH traders didn't nourish enough this poor creature.

### Block's important ratio of gas used (vs ETH value transfer)

<img src="/images/posts/cryptoaliens/023_px.png" width="50%" /><img src="/images/posts/cryptoaliens/016_px.png" width="50%" />

It often appears in combination with the previous criteria, if the ratio `total gas / total eth transfers` is high, meaning that a lot of the ETH is into gas, there will be some blobs at the end of the arms.

### ...and more block rare features

There are a lot of special cases are rare conditions that can happen. I will not disclose and I will let you discover. Some are really rare and some will be discovered in the future (even the author of blockstyle won't be aware of all cases!).

### Block's hash

Finally, the block hash gives variety in the results. It's necessary in order to have truly unique 12 millions species. But it's only complementary to the various other criteria. There are many features that are getting impacted by it, including the skin texturing (see _Mandelglitch BlockStyle_ section).

<img src="/images/posts/cryptoaliens/043_px.png" width="50%" /><img src="/images/posts/cryptoaliens/042_px.png" width="50%" />
<img src="/images/posts/cryptoaliens/012_px.png" width="50%" /><img src="/images/posts/cryptoaliens/038_px.png" width="50%" />

### What controls does the creator have?

At creation time, the minter also have the ability to move a bit the specimen:

- `mod1` is a simple rotation around it.
- `mod2` is a simple climbing and zooming.
- `mod3` will flex a bit the shape to make it torn & twist a bit.
- `mod4` have an impact on the color palette scaling.

**On top of this, mods have the ability to transform the skin texturing** which is actually based on [Mandelglitch BlockStyle](https://ethblock.art/create/17)! That means the rarity elements of Mandelglitch are shared in this new BlockStyle.

### mmh, Mandelglitch BlockStyle?

<a href="https://ethblock.art/create/17"><img src="/images/posts/cryptoaliens/mandelglitch.png" width="10%" /></a> **[Mandelglitch](https://ethblock.art/create/17) is a BlockStyle on [ethblock.art](https://ethblock.art/create/17), derived from Mandelbrot fractal.**

The visibility of Mandelglitch on the skin has been intentionally contained, but sometimes it is more visible. Here are two examples:

<img src="/images/posts/cryptoaliens/031_px.png" width="50%" /><img src="/images/posts/cryptoaliens/022_px.png" width="50%" />

## ...and, What's next?

Who knows what's next! As everything is available on the blockchain, what you mint is saved immutably and forever. Me or other artists could fork the code ([available on Github](https://github.com/gre/gre/tree/master/blockarts/CryptoAliens)) to make animated version of the CryptoAliens that were chosen (as this code is open source). Also we can imagine doing crossover between species or doing "evolution" of these species over time. Everything is possible!

---

See also [CryptoAliens: Genesis, a technical look][tech].

My name is greweb, and I'm a noise explorer. **feel free to ping me on Twitter [@greweb](https://twitter.com/greweb)**


CryptoAliens are digital creatures generated from Ethereum blockchain blocks. They can be minted on ethblock.at by anyone, which establishes a limited set of CryptoAliens species. Each block produced on Ethereum have unique elements that can be visualized in creative ways.

CryptoAliens: Genesis [ethblock.art]

[cookbook]: https://gl-react-cookbook.surge.sh
[github]: https://github.com/gre/gl-react
[jest]: https://github.com/facebook/jest
[headless-gl]: https://github.com/stackgl/headless-gl
[bus]: https://gl-react-cookbook.surge.sh/api#bus

# Happy to release **[https://gl-react-cookbook.surge.sh][cookbook]** containing 43 unique examples and API documentation!

<video src="/images/2016/12/gl-react-v3.mp4" width="100%" controls autoplay muted loop></video>

> If you don't want to be "spoiled" by this article, go through [the cookbook examples][cookbook]. This article will explore some of them.



## gl-react has been rewritten from scratch

**gl-react v3 is a complete rewrite of the v2 implementation for better performance and compatibility with React paradigm.**

This is not yet published on NPM as it's [still in development][github] (the Web version is pretty ready, React Native version is not implemented).

Most features provided by gl-react v2 are preserved (API haven't changed, [see how similar is the HelloGL example](https://gl-react-cookbook.surge.sh/hellogl)), but v3 fixes most Github issues accumulated for a year.

### The biggest mistake of the previous implementation

If there is one lesson learned from previous gl-react implementation: **"unfolding" / consuming the `children` prop by yourself is (probably) wrong, let React solve this job!** Using React, you can benefit [React reconciliation and diff algorithm](https://facebook.github.io/react/docs/reconciliation.html).
In other words, always prefer to keep users' VDOM tree rather than consuming it with `React.Children.*` functions.

I feel dumb not having discovered this before, but if you are not actually rendering DOM it's an easy path for a library to just map, traverse, consume the children tree and just render what you needs (like just a `<canvas/>`). But this is probably a mistake! First, this makes it impossible to use React Devtools and see the original tree, but more importantly, it breaks interoperability with other libraries (e.g. don't forbid someone to use [react-motion](https://github.com/chenglou/react-motion) or [React Router](https://github.com/ReactTraining/react-router) in the middle of your components!).

A better idea is to preserve the user `children`. Keep your logic in each Component and use the React lifecycle to create and destroy things, and **use [React context](https://facebook.github.io/react/docs/context.html) to connect children to parent**.

> You should better keep user `children`, even if it means rendering it in an empty `<span>`, _current workaround of `gl-react`, looking forward to hearing from you, idea inspired from the great [react-music](https://github.com/FormidableLabs/react-music)_

### What it means for gl-react

The gl-react v3 implementation truly uses React lifecycle: **a React Component update triggers a GL redraw**. That way, `shouldComponentUpdate` allows to do partial GL re-rendering. Each Node holds a [framebuffer object](https://www.opengl.org/wiki/Framebuffer_Object) (created on mount, destroyed on unmount) that only get redrawn when component updates and schedules a Surface reflow.

`<Node>` receives the `gl: WebGLRenderingContext` from the ancestor `<Surface>` thanks to [React context](https://facebook.github.io/react/docs/context.html). There is also a `glParent` context (a Surface or another Node) that is used to make GL components discoverable each other so we can build a dependency graph. This dependency graph allows to implement the correct `draw` pipeline (and it's pretty trivial, see [_Section "under the hood of Surface and Node redraw"_](#under_the_hook_redraw)).

## `<Bus>`, a better way to share computation

[gl-react used to automatically factorize the duplicates elements of the GL tree](http://greweb.me/2016/06/glreactconf/) but **it has been decided to remove this feature**: _This was actually a complex mechanism (a bit too "magic"), hard to implement and a premature optimization that can have slower performance._

The new gl-react embraces the React paradigm: The new way to express a Graph (and share computation) is **using a [`<Bus>`][bus]**...

### The `` `()=>ref` `` pattern

The problem we want to solve is to **express a graph with React**, which, at first glance, only allow to represent trees, not graphs!

The way we can solve this is by using refs and a "ref getter function":

1. **a Bus with a ref:** `<Bus ref="myBus">{content to inject}</Bus>`.
2. **pass a function that resolves the ref** to pipe Bus into another Node. e.g: `()=>this.refs.myBus`.

[blurmapdyn example](https://gl-react-cookbook.surge.sh/blurmapdyn)

<video loop autoplay controls src="/images/2016/12/blurmapdyn.mp4" width="100%"></video>

a single ConicalGradient should be used for all blur pass:
![](/images/2016/12/blurmapdynschema.png)

There are a few other good examples of ref usages:

- [blurmapmouse](https://gl-react-cookbook.surge.sh/blurmapmouse)
- [blurimgtitle](https://gl-react-cookbook.surge.sh/blurimgtitle) (same example that was features in 2016 React conf!)
- [behindasteroids](https://gl-react-cookbook.surge.sh/behindasteroids), crazy port of a game I made for js13k.

> The `()=>ref` pattern works only if you call the function after component did update (refs are set at this time).

## The good ol' children function

There is another pattern for more specific needs: instead of composing by giving an element, you can also compose by giving a **Function that returns an element**. Why that? Because, it's a way to nicely give you the redraw function: `redraw => <Video onFrame={redraw} />`:

[Checkout video example ![](/images/2016/12/videoredraw.png)](https://gl-react-cookbook.surge.sh/video?menu=true)

> We really just want to redraw if there is a new video frame.

We have merged the 2 patterns into one: if you provide a function, it's just called with `redraw`, and the returned value is used as a texture. We have a few cases to detect what kind of texture it is (and also an [extensible mechanism](https://gl-react-cookbook.surge.sh/api#textureloaders) used by implementations to load platform specific objects).
[(checkout this if you want to see the code)](https://github.com/gre/gl-react/blob/a33e6aa685479d588646b20dd62e1e25a64a5a47/packages/gl-react/src/Node.js#L704-L783)

## Node backbuffering & Backbuffer symbol

A new feature allows to inject the previous Node state as a texture. This is called backbuffering. One simple usecase is to implement Motion Blur persistence (like the GIF on top of this article).

We can also accumulate a state, for instance, to implement Game of Life!

[Game of life glider example ![](/images/2016/12/gol.gif)](https://gl-react-cookbook.surge.sh/golglider)

And the whole idea of gl-react (and React) is about composition. For instance, doing a rotating effect of that Game of Life is basically just `<Rotate> <GameOfLife /> </Rotate>`.

An interesting part is that you can update the GameOfLife at a rate that is independent from the **Rotate** rendering: just by making GameOfLife a pure component that receives a tick, or implementing shouldComponentUpdate update (you have as many choices as React have to [shortcut the rendering](https://facebook.github.io/react/docs/react-api.html#react.purecomponent)).

[golrotscu example![](/images/2016/12/golrot.gif)](https://gl-react-cookbook.surge.sh/golrotscu)

> See the counters that indicate the number of redraw. (the capture preview in the Box only get snapshot each 100ms, but in the real canvas, it runs at 60 FPS)

Finally, please checkout [ibex example](https://gl-react-cookbook.surge.sh/ibex) (extracted from another JS13K game! xD).

> You can't leave this article before seeing [ibex example](https://gl-react-cookbook.surge.sh/ibex)! I'm serious, this is probably the most accomplished code I ever wrote! xD

## <a name="under_the_hook_redraw"></a> under the hood of Surface and Node redraw

In order to make redraw efficient, `gl-react` have 2 phases: the `redraw()` phase and the `flush()` phase (reflecting the respective methods available both on `Surface` and `Node`). This is a bit like a rendering engine:

- **`redraw()` phase** sets a dirty flag to a Node and all its "dependents" (other nodes, buses, surface). _redraws happen generally bottom-up to the Surface._
- **`flush()` phase** draws all nodes that have the redraw flag. _draws happens top-down from the Surface._

`redraw()` is directly hooked to React update lifecycle (re-rendering a Node will calls `redraw()` for you).
To make this system efficient, **the flush() is by default asynchronous**, i.e. `redraw()` means scheduling a new gl draw.
Surface have a main loop that runs at 60 fps and call `flush()`. This is very efficient because if Surface does not have the redraw flag, `flush()` does nothing.

> In gl-react inspector, clicking on the redraw count will call `redraw()` on the node / bus. We can illustrate that only "dependents" get redrawn using the advanced [blurimgtitle example](https://gl-react-cookbook.surge.sh/blurimgtitle):

[only "dependents" get redrawn](https://gl-react-cookbook.surge.sh/blurimgtitle)

<video loop autoplay controls src="/images/2016/12/blurimgtitle-redraw.mp4" width="100%"></video>

This redraw/flush phases allow to prevent and skip rendering multiple times a Node. In some cases, we still want to redraw synchronously: with `<Node/>` `sync` prop. For instance, in Game of Life, we don't want to skip an update (the initial update set the initial GoL state, if it was async it might get skipped).

## Bonus

### Flow types

Flow types has been used for more robust code and better user experience. BTW, [WebGLRenderingContext will soon be released in flow](https://github.com/facebook/flow/pull/2764).

### Atom highlighting

If you are using Atom Editor, you can have JS inlined GLSL syntax highlighted.

![](https://cloud.githubusercontent.com/assets/211411/20623048/0527cce2-b306-11e6-85ee-5020be994c10.png)

_To configure this:_

- add `language-babel` package.
- Configure `language-babel` to add `GLSL:source.glsl` in settings "_JavaScript Tagged Template Literal Grammar Extensions_".
- (Bonus) Add this CSS to your _Atom > Stylesheet_:

```css
/* language-babel blocks */
atom-text-editor::shadow .line .ttl-grammar {
  /* NB: designed for dark theme. can be customized */
  background-color: rgba(0, 0, 0, 0.3);
}
atom-text-editor::shadow .line .ttl-grammar:first-child:last-child {
  display: block; /* force background to take full width only if ttl-grammar is alone in the line. */
}
```

### Tests: almost 100% coverage!

The library is tested directly on the command line, thanks to [Jest][jest] and [headless-gl][headless-gl] _(Big up to [mikolalysenko](https://github.com/mikolalysenko) for [headless-gl][headless-gl]!)_.
**gl-react have 2000 line of tests, involving a lot of gl calls, and readPixels, and it runs... in a few seconds!** _(to Jest devs: you are wizards!)_

```

 PASS  ./all.test.js
  ✓ renders a red shader (75ms)
  ✓ renders HelloGL (15ms)
  ✓ ndarray texture (27ms)
  ✓ renders a color uniform (18ms)
  ✓ composes color uniform with LinearCopy (21ms)
  ✓ no needs to flush if use of sync (24ms)
  ✓ Node can have a different size and be scaled up (18ms)
  ✓ Surface can be resized (32ms)
  ✓ bus uniform code style (17ms)
  ✓ bus example 1 (17ms)
  ✓ bus example 2 (18ms)
  ✓ bus example 3 (17ms)
  ✓ bus example 4 (22ms)
  ✓ bus example 5 (14ms)
  ✓ bus example 6 (24ms)
  ✓ bus: same texture used in multiple sampler2D is fine (14ms)
  ✓ a surface can be captured and resized (16ms)
  ✓ a node can be captured and resized (17ms)
  ✓ Uniform children redraw=>el function (22ms)
  ✓ Bus redraw=>el function (16ms)
  ✓ many Surface updates don't result of many redraws (18ms)
  ✓ many Surface flush() don't result of extra redraws (10ms)
  ✓ GL Components that implement shouldComponentUpdate shortcut Surface redraws (27ms)
  ✓ nested GL Component update will re-draw the Surface (24ms)
  ✓ Node `clear` and discard; (24ms)
  ✓ Node `backbuffering` (32ms)
  ✓ Node `backbuffering` in `sync` (36ms)
  ✓ texture can be null (12ms)
  ✓ array of textures (22ms)
  ✓ Node uniformsOptions texture interpolation (17ms)
  ✓ can be extended with addTextureLoaderClass (70ms)
  ✓ Surface `preload` prevent to draw anything (59ms)
  ✓ Surface `preload` that fails will trigger onLoadError (59ms)
  ✓ renders a shader inline in the Node (15ms)
  ✓ testing connectSize() feature (17ms)
  ✓ handle context lost nicely (43ms)
  ✓ Bus#uniform and Bus#index (25ms)
  ✓ VisitorLogger + bunch of funky extreme tests (140ms)

-------------------------------|----------|----------|----------|----------|----------------|
File                           |  % Stmts | % Branch |  % Funcs |  % Lines |Uncovered Lines |
-------------------------------|----------|----------|----------|----------|----------------|
All files                      |    97.85 |     88.8 |    95.96 |    99.35 |                |
 src                           |    97.82 |    88.95 |     95.9 |    99.35 |                |
  Backbuffer.js                |      100 |      100 |      100 |      100 |                |
  Bus.js                       |    96.15 |    74.29 |      100 |      100 |                |
  GLSL.js                      |      100 |       50 |      100 |      100 |                |
  LinearCopy.js                |      100 |      100 |      100 |      100 |                |
  NearestCopy.js               |      100 |      100 |      100 |      100 |                |
  Node.js                      |    97.65 |    92.71 |    97.01 |    99.01 |    214,216,358 |
  Shaders.js                   |      100 |    76.92 |      100 |      100 |                |
  Texture2DLoader.js           |      100 |      100 |      100 |      100 |                |
  TextureLoader.js             |      100 |      100 |      100 |      100 |                |
  TextureLoaderNDArray.js      |      100 |      100 |      100 |      100 |                |
  TextureLoaders.js            |      100 |      100 |      100 |      100 |                |
  Visitor.js                   |      100 |      100 |       75 |      100 |                |
  VisitorLogger.js             |      100 |    92.59 |      100 |      100 |                |
  Visitors.js                  |      100 |      100 |      100 |      100 |                |
  connectSize.js               |      100 |    85.71 |      100 |      100 |                |
  copyShader.js                |      100 |      100 |      100 |      100 |                |
  createSurface.js             |    97.09 |    83.61 |    94.55 |    99.32 |            361 |
  genId.js                     |      100 |      100 |      100 |      100 |                |
  index.js                     |      100 |      100 |      100 |      100 |                |
 src/helpers                   |      100 |       75 |      100 |      100 |                |
  disposable.js                |      100 |       50 |      100 |      100 |                |
  invariantNoDependentsLoop.js |      100 |      100 |      100 |      100 |                |
-------------------------------|----------|----------|----------|----------|----------------|
Test Suites: 1 passed, 1 total
Tests:       38 passed, 38 total
Snapshots:   4 passed, 4 total
Time:        2.655s
Ran all test suites.
```

One limitation is that all tests need to be in a single file. [I created an issue here](https://github.com/facebook/jest/issues/2029). I think it's either an issue in [Jest][jest] or in [headless-gl][headless-gl].

## Tradeoffs and remaining work

The library tradeoffs are written in [TRADEOFFS.md](https://github.com/gre/gl-react/blob/master/TRADEOFFS.md). We might cover some unexplored direction in a near future and solve some of them.

v3 is still in development, the main unfinished part is the React Native implementation which is now the main priority of the library.
It will probably rely on an awesome initiative: a React Native WebGL implementation started in Exponent by [@nikki](https://github.com/nikki93)!

For more information, see [v3 alpha: development in progress](https://github.com/gre/gl-react#v3-alpha-development-in-progress).

gl-react has been reimplemented from scratch, feedback from previous mistake and overview of new features.

gl-react v3

[relay]: https://github.com/facebook/relay
[relay-spec]: https://facebook.github.io/relay/docs/graphql-relay-specification.html#content

[Relay][relay] doesn't solve for you how you should render your components. Relay is "universal" and doesn't even assume it will be running in a browser context. It focuses only on providing an abstraction to work with GraphQL – the same way React focuses only on rendering. Each library solves one single problem at a time _(and hell, both are complex enough problem to solve already)_.

Because these libraries are very generic, it's now up to the community to solve the "more specific" parts. Just search on NPM and you can find tons of React libraries already, some might help you to solve part of the problem you want to solve.

This article demonstrates one use-case: **implementing a component handling the scroll of a list to pull more data** of a GraphQL connection with Relay.



## Usage

In React you should think in term of components that subdivide individual task to solve. To solve scrolling a connection you should just need this:

```js
<InfiniteScrollable relay={relay}>...</InfiniteScrollable>
```

Here is a real use-case we have at [projectseptember](https://projectseptember.com).

```js
import React, { Component, PropTypes } from "react";
import Relay from "react-relay";
import List from "material-ui/List";
import Content from "./Content";

class ContentStream extends Component {
  static propTypes = {
    relay: PropTypes.object.isRequired,
    user: PropTypes.object,
  };
  render() {
    const { user, relay } = this.props;
    return (
      <InfiniteScrollable relay={relay}>
        <List>
          {user.stream.edges.map((e) => (
            <Content content={e.node} key={e.cursor} />
          ))}
        </List>
      </InfiniteScrollable>
    );
  }
}

export default Relay.createContainer(ContentStream, {
  initialVariables: {
    first: 50,
  },
  fragments: {
    user: () => Relay.QL`
fragment on User {
  stream (first:$first) {
    edges {
      cursor
      node {
        ${Content.getFragment("content")}
      }
    }
  }
}
    `,
  },
});
```

We don't have to express how to "pull for more data" in that code. In fact, this is delegated to `InfiniteScrollable` and we never have to think again about it.

## InfiniteScrollable implementation

Relay enforces to implement [a subset of GraphQL spec](https://facebook.github.io/relay/docs/graphql-relay-specification.html#content), like the Connection API. It's a good thing because we can also rely on this fact, and what we only need is the `relay` object to implement a generic pull-on-scroll.

```js
import { Component, PropTypes } from "react";
import { findDOMNode } from "react-dom";

const regex = /(auto|scroll)/;

const style = (node, prop) =>
  getComputedStyle(node, null).getPropertyValue(prop);

const scroll = (node) =>
  regex.test(
    style(node, "overflow") +
      style(node, "overflow-y") +
      style(node, "overflow-x")
  );

const scrollparent = (node) =>
  !node || node === document.body
    ? document.body
    : scroll(node)
    ? node
    : scrollparent(node.parentNode);

const resizeEventOn = (n) => (n === document.body ? window : n);

export default class InfiniteScrollable extends Component {
  static propTypes = {
    children: PropTypes.any.isRequired,
    relay: PropTypes.object,
    style: PropTypes.object,
    loadPixelsInAdvance: PropTypes.number,
    relayVariable: PropTypes.string,
    chunkSize: PropTypes.number,
    // loadMore could even be generalize, this component works if you provide loadMore instead of relay
    loadMore: PropTypes.func, // (can) returns a promise
  };
  static defaultProps = {
    loadPixelsInAdvance: 1000,
    relayVariable: "first",
    chunkSize: 50,
  };

  state = { loading: false };

  resizeBoundOnDom = null;

  componentDidMount() {
    this.syncScrollBodyListener(this.props);
    this.checkScroll();
  }

  componentWillUnmount() {
    this.unbindResizeEvent();
  }

  componentDidUpdate() {
    this.syncScrollBodyListener();
  }

  unbindResizeEvent() {
    if (this.resizeBoundOnDom) {
      this.resizeBoundOnDom.removeEventListener("scroll", this.checkScroll);
      this.resizeBoundOnDom = null;
    }
  }

  getScrollParent() {
    return scrollparent(findDOMNode(this));
  }

  syncScrollBodyListener = () => {
    const resizeBoundOnDom = resizeEventOn(this.getScrollParent());
    if (resizeBoundOnDom !== this.resizeBoundOnDom) {
      this.unbindResizeEvent();
      resizeBoundOnDom.addEventListener("scroll", this.checkScroll);
    }
  };

  loadMoreUsingRelay = () => {
    const { relay, relayVariable, chunkSize } = this.props;
    return new Promise((resolve, reject) =>
      relay.setVariables(
        {
          [relayVariable]: relay.variables[relayVariable] + chunkSize,
        },
        (readyState) => {
          if (readyState.error) reject(readyState.error);
          if (readyState.done) resolve();
        }
      )
    );
  };

  checkScroll = () => {
    if (this.state.loading) return;
    const container = this.getScrollParent();
    if (!container) return;
    const { height } = container.getBoundingClientRect();
    const { scrollHeight, scrollTop } = container;
    const bottom = scrollTop + height;
    const { loadPixelsInAdvance } = this.props;
    const advance = bottom - scrollHeight + loadPixelsInAdvance;
    if (advance > 0) {
      this.setState({ loading: true }, () =>
        Promise.resolve({
          advance,
          bottom,
          scrollHeight,
          height,
          scrollTop,
          loadPixelsInAdvance,
        })
          .then(this.props.loadMore || this.loadMoreUsingRelay)
          .then(
            () => this.setState({ loading: false }), // technically could recall checkScroll here. in second callback of setState. fork it, try it, adapt it !
            (e) => (console.warn(e), this.setState({ loading: false }))
          )
      );
    }
  };

  render() {
    // you might want to render a spinner?
    // children might be a function?
    // etc..
    // these are some variations we could have from this starting point
    return this.props.children;
  }
}
```

This is a **possible implementation** of this problem. You might want to add more things based on your needs. For instance you could automatically render a loading spinner... or a million other things! Please try it, fork it, give feedback :)

It is also possible to implement it as a High Order Component (HOC): [https://github.com/facebook/relay/issues/1377](https://github.com/facebook/relay/issues/1377).

implement a component handling the scroll of a list to pull more data of a Graphql Connection with Relay

Relay, scrolling connections

[twitter]: https://twitter.com/ProjSeptEng
[website]: https://projectseptember.com
[rn]: http://facebook.github.io/react-native/
[graphql]: http://graphql.org/
[scala]: http://scala-lang.org/
[glreactconf]: /2016/06/glreactconf
[glreact]: https://github.com/ProjectSeptemberInc/gl-react
[glreactdom]: https://github.com/ProjectSeptemberInc/gl-react-dom
[glreactnative]: https://github.com/ProjectSeptemberInc/gl-react-native
[rnanimation]: https://facebook.github.io/react-native/docs/animations.html

🎉 Hooray! [We][twitter] recently released an iOS app called [Project September][website].

This application is built with nice tech stack including [React Native][rn] and [GraphQL][graphql]. The backend is powered by [Scala][scala], a robust functional language, and we use many other [cool techs][twitter].

This fashion app needed some fancy features: one was demo-ed at last [React.js conference][glreactconf] with the ability to do localized blur on text over images.

We have developed **[`gl-react`][glreact]** to abstract GL in React paradigm – with two companion libraries [`gl-react-dom`][glreactdom] and [`gl-react-native`][glreactnative] that glues React Native with OpenGL.

Let's first see 2 demos of OpenGL usage in our app, and then we'll write a bit about how it's hard to get animations right.



## The Text Over Image blur

### The goal

<img width="50%" src="/images/2016/07/current-1.png" /><img width="50%" src="/images/2016/07/current-2.png" />

### How it works

<img src="/images/2016/07/initial.png" />

**+** **_(layer)_**

<img src="/images/2016/07/layer.png" />

**=**

<img src="/images/2016/07/result.png" />

### Under the hood

- The shadow intensity, size, position, is procedurally generated, we can adjust that. The shadow color is the blurry image color
- The text color is determined by the color picked in blurred image at the shadow middle position. **If the `monochrome` value of that color is lower than 60%**, text will be white, otherwise text will be black.

Here is more detail on how the shadow is generated:

<img src="/images/2016/07/under-1.png" />

**\* (multiply alpha)**

<img src="/images/2016/07/under-2.png" />

**=**

<img src="/images/2016/07/under-3.png" />

**+ (layer)**

<img src="/images/2016/07/under-4.png" />

**=**

<img src="/images/2016/07/layer.png" />

### Fragment shader

```glsl
precision highp float;
varying vec2 uv;

uniform sampler2D img;
uniform sampler2D imgBlurred;
uniform sampler2D txt;

const vec2 shadowCenter = vec2(0.5, 0.9);
const vec2 shadowSize = vec2(0.6, 0.2);
float shadow () {
  return 0.8 * smoothstep(1.0, 0.2, distance(uv / shadowSize, shadowCenter / shadowSize));
}
float monochrome (vec3 c) {
  return 0.2125 * c.r + 0.7154 * c.g + 0.0721 * c.b;
}
vec3 textColor (vec3 bg) {
  return vec3(step(monochrome(bg), 0.6));
}

void main () {
  vec4 bg = mix(texture2D(img, uv), texture2D(imgBlurred, uv), shadow());
  vec4 fg = vec4(textColor(texture2D(imgBlurred, shadowCenter).rgb), 1.0);
  float fgFactor = 1.0 - texture2D(txt, uv).r;
  gl_FragColor = mix(bg, fg, fgFactor);
}
```

### Integration

```html
<GL.Node shader="{shaders.textOverImage}">
  <GL.Uniform name="img"> {img} </GL.Uniform>
  <GL.Uniform name="imgBlurred">
    <Blur factor="{20}" passes="{6}" width="{width}" height="{height}">
      {img}
    </Blur>
  </GL.Uniform>
  <GL.Uniform name="txt">
    <Text style="{titleStyle}">{title}</Text>
  </GL.Uniform>
</GL.Node>
```

## Uploading Thumbnail

This is a video record of our app:

<video controls autoplay muted loop width="100%" src="/images/2016/07/upload.mp4"></video>

The uploading spinner effect is implemented with an OpenGL shader. This was not easy to avoid all the blinks we used to have. We have different components to render each step (uploading animation / uploaded final image) and the uploaded image needs to be downloaded again to not render as white. One solution could be to use a monolithic "thumbnail" component that do everything. We wanted to keep independent components.
Hopefully, everything now works seamlessly with some "double buffering"/swapping mechanism we will explained at the end of this article.

## Animate all the things

### Designing animations

> Fluid, meaningful animations are essential to the mobile user experience.
> **[— React Native Animations documentation][rnanimation]**

It's not easy to design how an application should animate, to define transitions between all the different possible single state and edge-cases of your app. Designing animations, as part of UX design, is a time consuming work but it tends to be underestimated while being essential for moving from a _good app_ to a _very good app_. That tends to be the last 20% remaining missing parts of your app that are the hardest but that makes the 80% of a great UX.

### Implementing animations

Not only it's hard to have figured out the animations (to find the optimal UX) but it can also be quite challenging to implement them in a maintainable and robust way. Turns out most of the times, your code is not ready for it and it implies big refactoring.

#### in React Native

React Native [Animations API][rnanimation] makes it easier: you just have to switch to one of the `Animated.*` component. In `gl-react` we even support Animated values to flow into the shaders uniforms so it's very convenient to animate a GL effect.

That said, React Native Animations is not the ultimate silver bullet. There are things Animations won't solve for you. React Native Animated is still a low level API, it's also imperative and not opinionated on how you should turn it into descriptive paradigm.

I guess what's generally hard with animations in React functional/descriptive paradigm ("always `render()`ing Virtual DOM again" idea) is to figure out **how to not "break" your animations**. For instance, ugly animation interruption could happen if you `render()` a different component: because it forces the component to unmount. If you have an animation happening, you might not want it to stop, or at least you might want to smoothly customize the transition to the new state.

That's something CSS transitions might help solving, but in React Native we don't have them, so it's not so trivial.

##### our current solution

We have built our own abstraction to solve this problem: a Component decorator manages to kill a lot of flashes and blinks cases (e.g. images not ready yet, animation getting interrupted).

> What the decoration solves: when moving from A to B, you want B to be ready (e.g. images are loaded), you also want A to have finish its (animated) work.

**A component can express it needs some time to mount _(e.g. an image to load!)_ OR that it needs some time to unmount _(e.g. an "animating out")_. This will basically hold the rendering to happen:**

The decoration can implement "double buffering" on a Component: `render()` function keeps rendering Component with the previous "stable props" but will also render in background another instance of Component with the next props. When that next props Component is ready and loaded, we can successful swap it to be the new "stable props".

You have the basic idea, the decorator is not so trivial to implement as it also needs to handle some edge-cases, for instance if the decorator receives new props during the transition. We also have a minimal way to express "styles transitions" similarly to how CSS Transitions works.

🎉 There are some OpenGL in the Project September fashion app!

Universal GL Effects for Web and Native

<img src="/images/2015/10/gl-react.png" alt="" class="thumbnail-left" /> Last Thursday, my talk at [React Paris Meetup](http://www.meetup.com/ReactJS-Paris/events/226103821/) was about using **the functional rendering** paradigm of **WebGL** in **React**. The library [`gl-react`](https://github.com/ProjectSeptemberInc/gl-react) wraps WebGL in React paradigm with a focus for developing 2D effects, that we need in my current startup, [Project September](https://twitter.com/ProjSeptEng), where I have the chance to develop it.

## [Slides](http://greweb.me/reactmeetup7)

<iframe src="http://greweb.me/reactmeetup7" width="600" height="400" frameborder="0"></iframe>



## Abstract

We can write effects without having to learn the complex and imperative low-level WebGL API but instead composing React components, as simple as functional composition, using VDOM descriptive paradigm.

[gl-react](https://github.com/ProjectSeptemberInc/gl-react) brings WebGL bindings for react to implement complex effects over content.

[gl-react-native](https://github.com/ProjectSeptemberInc/gl-react-native) is the React Native implementation,
therefore allows universal effects to be written both for web and native.

These libraries totally hides for you the complexity of using the OpenGL/WebGL API but takes the best part of it: GLSL, which is a "functional rendering" language that runs on GPU.

This presentation is an introduction to WebGL in React and functional programming concept and showcases made with gl-react and gl-react-native

Introducing gl-react

_^ Sorry guys, you may have notice the blog post date is wrong. I won't change the URL, but thanks to how time works, this will be fixed in one month anyway :-D_

[ReactEurope](https://twitter.com/chantastic/status/616608931037646850) conference
was to me incredibly [inspiring](https://twitter.com/chantastic/status/616670658911715328) and [promising](https://twitter.com/chantastic/status/616995607043903488).
Yersterday got tons of news and tweets from JavaScript community.

One tweet and blog post by the great [@aerotwist](https://twitter.com/aerotwist) got my attention.

<blockquote class="twitter-tweet" data-cards="hidden" lang="fr"><p lang="en" dir="ltr">I often hear claims that “the DOM is slow!” and “React is fast!”, so I decided to put that to the test:&#10;&#10;<a href="https://t.co/M1RZZiyVT2">https://t.co/M1RZZiyVT2</a>&#10;&#10;🐢vs🐇</p>&mdash; Paul Lewis (@aerotwist) <a href="https://twitter.com/aerotwist/status/616934953679458304">3 Juillet 2015</a></blockquote>

I would like to express here my opinion and feedback on using React.

I've been using React for almost 2 years now, and always in performance intensive use-cases, from Games to WebGL.

<a href="http://diaporama.glsl.io/" target="_blank">
<img src="/images/2015/07/diaporama_3.jpg" alt="" class="thumbnail-left" />
</a>

I've created [glsl.io](http://glsl.io/) and I'm working on [Diaporama Maker](https://github.com/gre/diaporama-maker).
Both applications are built with React and combined use of HTML, SVG, WebGL.

Diaporama Maker is probably the most ambitious piece of software I've ever personally done.

<br style="clear: left" />

> In short, [Diaporama Maker](https://github.com/gre/diaporama-maker) it is a WYSIWYG editor for web slideshow (mainly photo slideshows). It is a bit like iMovie with the web as first target. [The project is entirely open-sourced.](https://github.com/gre/diaporama-maker)

Currently, I am able to render the whole application at 60 FPS and this is still unexpected and surprising to me
(press Space to run the diaporama on [diaporama.glsl.io demo](http://diaporama.glsl.io/)).
Well, more exactly, this would not have been possible without some optimizations
that I'm going to detail a bit at the end of this article.



## The point is productivity

I don't think Virtual DOM claims to be faster than doing Vanilla DOM, and that's not really the point. **The point is productivity.**
You can write very well optimized code in Vanilla DOM but this might require **a lot of expertise**
and a lot of time even for an experienced team _(time that should be spent focusing on making your product)_.

When it comes to adding new features and refactoring old ones, this goes worse.
Without a well constrained framework or paradigm, things does not scale far, are time consuming and introduce bugs,...
Especially in a team where multiple developers have to work with each other.

> **See Also:** [Why does React scale?](https://www.youtube.com/watch?v=D-ioDiacTm8) by [@vjeux](https://twitter.com/Vjeux).

## What matters to me

There is a lot of advantages of using Virtual DOM approach before talking about React performances.

Of course, this always depends on what you are building, but I would claim that
**there is a long way to go using React before experiencing performance issues**,
and in the worse cases: **you can almost always find easy solutions to optimize these performance issues**.

### DX

React has an incredible Developer eXperience (that people seem to call DX nowadays!) that can [help you improving UX](https://twitter.com/greweb/status/617258379183005696) and the ability to [measure Performances](https://facebook.github.io/react/docs/perf.html) and [optimize them](https://facebook.github.io/react/docs/component-specs.html#updating-shouldcomponentupdate) when you reach bottlenecks.

You can easily figure out which component is a bottleneck in the Component tree as shown in following screenshot.

> ![](/images/2015/07/diaporama-perfs.png)
> With printWasted() you can see how much time React has wasted to `render()` something that didn't change and how much instances has been created. (there is also printInclusive and printExclusive)

This is a bit equivalent of the Web Console Profiler except it emphasis on your application components which is a very relevant approach.

### React data flow

> I can't imagine re-writing Diaporama Maker in Vanilla DOM.

In Diaporama Maker, I have a lot of cross dependencies between components,
for instance the current `time` is shared and used everywhere in the application.
As a matter of fact, dependencies grow when adding more and more features.

> ![](/images/2015/07/diaporama_configure_kenburns.gif)
> usages of time in 3 independent components.

**The descriptive Virtual DOM approach very simply solves this problem**.
You just have to pass props in to share data between components:
there is one source of trust that climb down your component tree via "props".

![](/images/2015/07/diaporama-maker-time-props.jpg)

With Virtual DOM approach, the cost to add one new dependency to a shared data is small and **does not become more complex as the application grows**.

> ![](/images/2015/07/diaporama_slide_content.gif)
> another more complex showcase of shared states.

Using an Event System like you would do in standard Backbone approach tends to lead to imperative style and spaghetti codes (and when using global events, components are not really reusable).

Moreover, I think that `Views<->Models` Event System approach, if not carefully used, tends to converge to an unmaintainable and laggy applications.

### React is a Component library

React truly offers **component as first-class citizen**.
This means it allows component reusability. I've tried alternative like virtual-dom and I don't think it emphasizes enough on this benefit.

There are [important good practices](https://twitter.com/chantastic/status/616997918155759616) when using React like minimizing states and props and I'm not going to expand more on this subject. Most of these best practices are not exclusive to React but come from common sense and software architecture in general.
One of the important point for performance is to **choose a good granularity of your component tree**.
It is generally a good idea to split up a component into pieces as small as possible
because it allows to separate concerns, minimize props and consequently optimize rendering diff.

#### Diaporama Maker architecture

You would be surprised to know that Diaporama Maker does not even use **Flux** (that might be reconsidered soon for collaborative features). I've just taken the old "callback as props" approach all the way down the component tree. That easily makes all components purely modular and re-usable (no dependencies on some Stores).
I've also taken the [inline style approach]() without actually using any framework (this is just about props-passing `style` objects).

As a consequence, I've been able to externalize a lot of tiny components that are part of my application
so I can share them across apps and also in order to people to re-use them.

What is important about externalizing components is also the ability to test and optimize them independently (the whole idea of modularity).

Here are all the standalone UI components used by Diaporama Maker:

- [bezier-easing-editor](https://github.com/gre/bezier-easing-editor)
- [bezier-easing-picker](https://github.com/gre/bezier-easing-picker)
- [diaporama-react](https://github.com/glslio/diaporama-react)
- [glsl-transition-vignette](https://github.com/glslio/glsl-transition-vignette)
- [glsl-transition-vignette-grid](https://github.com/glslio/glsl-transition-vignette-grid)
- [glsl-uniforms-editor](https://github.com/gre/glsl-uniforms-editor)
- [kenburns-editor](https://github.com/gre/kenburns-editor)

(each one have standalone demos)

## Optimizing performances

<blockquote class="twitter-tweet" lang="fr"><p lang="en" dir="ltr">I&#39;ve been working on crazy projects using React (like <a href="http://t.co/U2oETh5lhZ">http://t.co/U2oETh5lhZ</a> ). most performance issues i&#39;ve met was not because of React</p>&mdash; greweb (@greweb) <a href="https://twitter.com/greweb/status/617210444839809024">4 Juillet 2015</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

Here are 2 examples of optimizations I had to do in Diaporama Maker that are not because of React:

- It is easy to write not very optimized WebGL, so I work a lot to optimize the pipeline of [Diaporama engine](https://github.com/gre/diaporama)
- CSS transforms defined on Library images was for a time very intensive for the browser to render so I am now using server-resized "thumbnails" instead of the full-size images. Asking the browser to recompute the `transform: scale(...)` of 50 high resolution images can be super costy. (without this optimization, the resize of the application was running at like 2-3 FPS because the library thumbnails need to recompute their scale and crop).

But what if you still have performance issue due by React? Yes this can happens.

### Timeline Grid example

In Diaporama Maker, I have a Component that generates a lot of elements (like 1300 elements for a 2 minutes slideshow) and my first naive implementation was very slow. This component is [TimelineGrid](https://github.com/gre/diaporama-maker/blob/b0c6447b127785bea3c2487b0c77037418298b8c/client/ui/TimelineGrid/index.js) which renders the timescale in the timeline. It is implemented with SVG and a lot of `<text>` and `<line>`.

The performance issue was noticeable when drag and dropping items across the application. React was forced to render() and compare the whole timescale grid every time. But the timescale does not change! it just have 3 props:

```xml
<TimelineGrid timeScale={timeScale} width={gridWidth} height={gridHeight} />
```

**So it was very easy to optimize it just by using the `PureRenderMixin` to say to react that all my props are immutable.**
(I could have implemented `shouldComponentUpdate` too).

After this step, and for this precise example, I don't think a Vanilla DOM implementation can reach better performance:

- when one of the grid parameter change, **EVERYTHING** need to be recomputed because all scales are changing.
- React is doing even smarter thing that I would not manually do? Like reusing elements instead of destroying/creating them.

There might still be ways to go more far in optimizing this example. For instance I could chunk my grid into pieces
and only render the pieces that are visible, like in an infinite scroll system _(I could use something like [sliding-window](https://github.com/gre/sliding-window) for this)_.
That would probably be premature optimization for this example.

## Wrap Up

To my mind, generic benchmarks always tends to be biased and does not represent use-cases reality unless you are really covering your application itself.

The TimelineGrid component optimization explained in this article is a very specific and well chosen example,
but it is one counter-example for such a benchmark.

Each application has its own needs and constraints and we can't really generalize one way to go.
Also Performance should not be the main concern to choose a technology.

It is easy to make Virtual DOM library benchmarks,
comparing the performance of rendering and Array diffing,
but does that covers 80% of use-cases?
Is performance really the point?
What tradeoff do you accept to make between Performance and Productivity?

Tell me what you think.

In the meantime, I think we can all continue getting applications done
and [developing amazing DX](https://github.com/gaearon/react-hot-loader).

I would like to express here my opinion and feedback on using React and performance optimization you can do.

Making performant React applications

A talk I did at webglparis to present GLSL.io and GLSL Transitions initiative.

[FR] webglparis talk: GLSL.io initiative and WebGL Transitions

[gamepost]: /2014/09/ibex
[js13kgames]: http://js13kgames.com/
[submission]: http://js13kgames.com/entries/ibex
[github]: http://github.com/gre/js13k-2014
[cellular]: http://en.wikipedia.org/wiki/Cellular_automaton
[wolfram]: http://en.wikipedia.org/wiki/Stephen_Wolfram
[ankos]: https://www.wolframscience.com/
[gol]: http://en.wikipedia.org/wiki/Conway's_Game_of_Life
[cavelikegen]: http://www.roguebasin.com/index.php?title=Cellular_Automata_Method_for_Generating_Random_Cave-Like_Levels
[logicfrag]: https://github.com/gre/js13k-2014/blob/master/src/shaders/logic.frag

<a href="/2014/09/ibex">
  <img src="/images/2014/09/ibex-2.png" alt="" class="thumbnail-right" />
</a>

Last week I finished my [JS13K game called "IBEX"][gamepost],
an apocalyptic game where you have to help some wild ibex to escape from the inferno.

> IBEX received the 16th place (out of 129 games) from the [js13kgames][js13kgames] jury.

This article is a technical post-mortem about the development of this game in JavaScript / WebGL
and how the world is just **ruled with [cellular automata][cellular]**
and computed efficiently in a GLSL shader.

<iframe width="50%" height="220" src="//www.youtube.com/embed/nqD2qIy4auU" frameborder="0" allowfullscreen></iframe>



## Cellular automata ruled world

A **Cellular Automaton** (plurial Cellular Automata) is an **automaton** _(in other words, a state machine)_
based on **a grid (an array) of cells**.
It has been discovered years ago and popularized by [Stephen Wolfram][wolfram]
in his interesting book [A new Kind of Science][ankos].

<figure class="thumbnail-right">
  <img src="/images/2014/09/elementary-automaton.png" />
  <figcaption>
    <a href="http://mathworld.wolfram.com/ElementaryCellularAutomaton.html">
      elementary automata.
    </a>
  </figcaption>
</figure>

The simplest possible cellular automaton is the one where, at each generation,
the cell value is determined from the **previous and the 2 adjacent cells** (left and right)
value and where the value can only be **0 or 1** (white or black / true or false).
The way the cell value is determined is through a set of rules.

> In an elementary cellular automaton, there is a total of 8 rules, which means 256 possible cellular automata.

### 2D cellular automaton

<figure class="thumbnail-left">
  <img src="/images/2014/09/Gospers_glider_gun.gif" />
  <figcaption>
    <a href="http://en.wikipedia.org/wiki/Conway's_Game_of_Life">Conway's Game of Life</a>,
    a well known 2D cellular automaton.
  </figcaption>
</figure>

The kind of Cellular Automaton I focused on for my game is **2D cellular automaton**:
At each generation, the cell value is determined from **the previous value and the 8 adjacent cells**
using a finite set of rules.

It is important to understand that these rules are applied in parallel for **all** cells of the world.

<br />

<figure class="thumbnail-right">
  <img src="/images/2014/09/ibex-experiment2.png" />
  <figcaption>
    Early version with 4 elements and simple rules:
    Water falls in Air, Fire grows in Air, Water extinguishes Fire, Earth drops Water + creates Fire
  </figcaption>
</figure>

**A 2D cellular automaton rule:**

![](/images/2014/09/ibex-rule-2d.png)

What I've found is that
**the WebGL and the GLSL language works well to implement a cellular automaton**.

The GLSL paradigm is what I like to call [functional rendering](/2013/11/functional-rendering/):
It is, to simplify, a function **`(x,y) => (r,g,b,a)`**:
You fundamentally have to implement this function which **gives a color for a given viewport position**,
and you implement it in a dedicated language which compiles to the GPU.

So we can implement a 2D cellular automaton where each cell is a real (x,y) position in the Texture
and where the (r,g,b,a) color is used to encode your possible cell states, and that's a lot of possible encoding!

In my game, i've chosen to only use the `"r"` component to implement the cell state.
But imagine all the possibilities of encoding more data per cell (like the velocity, the amount of particle in the cells,...).

**Here is a boilerplate of making a Cellular Automaton in GLSL:**

```glsl
uniform sampler2D state; // the previous world state texture.
uniform vec2 size; // The world size (state texture width and height)

/*
 The decode / encode functions provide an example of encoding
 an integer state in the "r" component over possible 16 values.
 You can definitely implement your own. Also "int" could be something more complex
 */
int decode (vec4 color) {
  return int(floor(.5 + 16.0 * texture2D(state, uv).r));
}
vec4 encode (int value) {
  return vec4(float(r) / 16.0,  0.0, 0.0, 1.0);
}

/*
  get(x,y) is doing a lookup in the state texture to get the (previous) state value of a position.
 */
int get (int x, int y) {
  vec2 uv = (gl_FragCoord.xy + vec2(x, y)) / size;
  return (uv.x < 0.0 || uv.x >= 1.0 || uv.y < 0.0 || uv.y >= 1.0) ? 0 :
    decode(texture2D(state, uv).r);
}

void main () {
  // We get all neighbors cell values from previous state
  int NW = get(-1, 1);
  int NN = get( 0, 1);
  int NE = get( 1, 1);
  int WW = get(-1, 0);
  int CC = get( 0, 0);
  int EE = get( 1, 0);
  int SW = get(-1,-1);
  int SS = get( 0,-1);
  int SE = get( 1,-1);

  int r; // r (for result) is the new cell value.

  ////////////////////////////
  // NOW HERE IS THE COOL PART
  // where you implement all your rules (from the 9 state values)
  // and give a value to r.
  ////////////////////////////

  gl_FragColor = encode(r);
}
```

> **The complete game rules are all implemented in a GLSL fragment shader:
> [logic.frag][logicfrag]**.
> It is important to understand that this fragment shader takes in input
> the previous world state (as an uniform texture)
> and computes a new state by applying the rules.

On the JavaScript side, you need to **give an initial state to the texture**
(so you need to also encode data the same way it is done in the shader).
Alternatively you can also make a shader to do this job
_(generating the terrain can be intense to do in JavaScript, like it is the case for my game...)_.

Also if you want to **query the world from JavaScript**,
_(e.g. you want to do physics or collision detection like it is also the case for my game)_,
you need to use `gl.readPixels` and then decode data in JavaScript.

I'll explain this a bit later in another article.
Let's now go back to the Cellular Automaton used in IBEX.

<figure>
  <img src="/images/2014/09/ibex-screenshot1.png" />
  <figcaption>
    The different elements gameplay.
  </figcaption>
</figure>

### The elements

The game theme was "Four Elements: **Water, Air, Earth, Fire**", so I've used
these 4 elements as primary elements of the cellular automaton.

Each elements also have secondary elements that can be created from each other interactions:
**Source, Volcano, Grass, WindLeft, WindRight**.

- The **Volcano** is lava growing in the Earth. It creates Fire (when there is Air).
- The **Source** is water infiltrating in the Earth. It drops Water (when there is Air).
- The **Grass** (or Forest) grows on Earth with Water. It is a speed bonus for ibex but it propagates fire very fast. It also stop the water from flowing.
- The **Wind** (left or right wind) is created randomly in Air. It have effects on Water and Fire propagation and also on ibex speed.

**Some constants...**

```glsl
// Elements
int A  = 0; // Air
int E  = 1; // Earth
int F  = 2; // Fire
int W  = 3; // Water
int V  = 4; // Volcano
int S  = 5; // Source
int Al = 6; // Air Left (wind)
int Ar = 7; // Air Right (wind)
int G  = 8; // Grass (forest)
```

<figure class="thumbnail-right">
  <img src="/images/2014/09/ibex-experiment1.png" />
  <figcaption>
    Fun and experimental result accidentally produced in an early development of the rules.
  </figcaption>
</figure>

To summary, there is 9 possible elements,
and rules are determined from the 9 previous cells:
This makes a LOT of possible rules.
However, the rules involved here remain simple and with just a few rules.

> That is the big thing about cellular automata:
> very simple rules produce an incredible variety of results.

In general, we can classify my game rules into 2 kind of rules:
"interaction" rules and "propagation" rules.
The first kind describes how two (or more!) elements interact each other.
The second kind describes the way an element evolve.
Some rules will also mix them both.

### Some simple "propagation rule"

**Earth stays:**
an Earth is returned if there was an Earth before.

![](/images/2014/09/ibex-rule-earth.png)

**Water falls in Air:**
a Water is created if there was a Water on top.

![](/images/2014/09/ibex-rule-water1.png)

**Fire grows in Air:**
a Fire is created if there was a Fire on bottom.

![](/images/2014/09/ibex-rule-fire1.png)

These rules produce very elementary result, we will now see how we can improve them.

### Weights in rules

**More powerful rules can also be reached by using weights**:
you can affect a weight for each neighbor cell to give more or less importance to them.

Let's take a look at a simple example:

![](/images/2014/09/ibex-rule-gencave-example.png)

> N.B.: only the "sum" is considered in the rule:
> if an element matches, we sum the weight of the cell, otherwise "zero".

**This example is actually a weighted version of [the cave rule you can find here][cavelikegen]:**

<figure>
  <figcaption>
    Result of the rule, with (Air or Earth) random pick for each  initial cell value.
  </figcaption>
  <img src="/images/2014/09/ibex-gencaveresult.png" />
</figure>

### Randomness in rules

**Combine Randomness and Weights and you get a very powerful simulation.**

To avoid seeing some (well known) patterns in the simulation I added some randomness in my rules.
**With randomness, the results are incredibly powerful.**

In the following video, notice how cool the fire propagation can result
by varying the propagation randomness factor.

<iframe width="100%" height="420" src="//www.youtube.com/embed/mF-MNHk7u4s" frameborder="0" allowfullscreen="allowfullscreen"></iframe>

**The code:**

```glsl
#define AnyADJ(e) (NW==e||SE==e||NE==e||SW==e||NN==e||SS==e||EE==e||WW==e)
// ^^^^^^^^ MACRO !
if (
  CC == G &&
  RAND < firePropagation &&
  ( AnyADJ(F) || AnyADJ(V) )) {
  r = F;
}
```

#### Randomness in GLSL ???

GLSL is fully stateless and there is **NO WAY** to have a `random()` function in the GPU.
The trick to do randomness in GLSL is by invoking some math black magic:

```glsl
float rand(vec2 co){
  return fract(sin(dot(co.xy ,vec2(12.9898,78.233))) * 43758.5453);
}
```

**`rand`** is a [popular](http://stackoverflow.com/questions/4200224/random-noise-functions-for-glsl)
function which returns a pseudo-random value (from 0.0 to 1.0) for a given position.

My personal **black magic** was to define a convenient macro to have a "RAND" word which would get me
a new random number.

```glsl
#define RAND (S_=vec2(rand(S_), rand(S_+9.))).x
```

`S_` is a seed which is accumulated when calling this `RAND`.
Because this macro will be inlined in the code, `S_` must be defined in a local variable
(so in summary, `RAND` is doing local side-effect).

```glsl
vec2 p = gl_FragCoord.xy;
vec2 S_ = p + 0.001 * time;
```

Note that **the current pixel position** itself AND **the time** are both used for initializing the seed.
It produces **variable randomness over time and for each pixel**.

Let's now see other examples where randomness can be very powerful.

### The Water and Fire interactions

**Fire grows and diverges**:

![](/images/2014/09/ibex-rule-fire2.png)

- the "left" and the "right" columns in this rule allows **divergence** in the way fire grows:
  Instead of growing straight up, **the fire can also move a bit left or a bit right**.
  A lower weight for these side columns make the fire diverge a bit less than a "triangle" propagation.

Here is the GLSL code:

```glsl
// Fire grow / Fire + Water
if (
  -0.05 * float(NW==W) + -0.40 * float(NN==W) + -0.05 * float(NE==W) + // If water drop...
  -0.50 * float(WW==W) + -0.50 * float(CC==W) + -0.50 * float(EE==W) + // ...or water nearby.
   0.35 * float(SW==F) +  0.90 * float(SS==F) +  0.35 * float(SE==F)   // Fire will move up and expand a bit.
 >= 0.9 - 0.6 * RAND // The sum of matched weights must be enough important, also with some randomness
) {
  r = F;
}
```

**Water falls, diverges and creates holes**:

![](/images/2014/09/ibex-rule-water2.png)

<figure class="thumbnail-right">
  <img src="/images/2014/09/ibex-rain.png"/>
  <figcaption>The rain in IBEX. Notice how Water diverges a bit and creates holes.</figcaption>
</figure>

- Same as the fire rule, we also have **divergence** in the water.
- However there is one more important thing in the rule:
  thanks to the **double inequality**,
  Water is created only if there is not already too much Water:
  it **results of creating Air between the Water particules**.
  This make Water elements to be less compact than Fire elements,
  the water does not visually "expand" contrary to the fire.
- The **randomness** helps a lot here to give **no visible patterns** in this job.

<br />

Here are all rules which creates Water:
in this rules you can also notice how **the Water flows on Earth** and how
the **occasional rain** is implemented.

```glsl
if (
// Water drop / Water + Fire
  between(
    0.3 * float(NW==W) +  0.9 * float(NN==W) +  0.3 * float(NE==W) +
    0.1 * float(WW==W) + -0.3 * float(CC==F) +  0.1 * float(EE==W) +
                         -0.3 * float(SS==F)
    ,
    0.9 - 0.6 * RAND,
    1.4 + 0.3 * RAND
  )

  || // Water flow on earth rules

  !prevIsSolid &&
  RAND < 0.98 &&
  ( (WW==W||NW==W) && SW==E || (EE==W||NE==W) && SE==E )

  || // Occasional rain
  !prevIsSolid &&
  p.y >= SZ.y-1.0 &&
  rainRelativeTime < 100.0 &&
  between(
    p.x -
    (rand(vec2(SD*0.7 + TI - rainRelativeTime)) * SZ.x) // Rain Start
    ,
    0.0,
    100.0 * rand(vec2(SD + TI - rainRelativeTime)) // Rain Length
  )

  || // Source creates water
  !prevIsSolid && (
    0.9 * float(NW==S) +  1.0 * float(NN==S) +  0.9 * float(NE==S) +
    0.7 * float(WW==S) +                        0.7 * float(EE==S)
    >= 1.0 - 0.3 * RAND
  )
) {
  r = W;
}
```

**Source rules**

The Source can be created in the Earth by two rules:
Either there is enough water around,
Or there is source on top.

Note the important usage of randomness.

![](/images/2014/09/ibex-rule-source.png)

### The grass propagation, Limiting the forest height

To finish, the grass needed a special extension to the so-far-used 2D cellular automaton,
the grass cell value is not only being determined from the 8 adjacent cells:

To have more complex structure, **the grass is determined
from the previous cell at position `(x, y-N)`**,
where x and y is the cell position and N is a variable value (random but constant per cell position).
In other word, a forest can grow if the cell at N step under it is not a forest.
This extra rule just adds a constraint on the max height that a forest can have.

<figure>
  <figcaption>A Grass can be created if the (x,y-N) cell is not a Grass.</figcaption>
  <img src="/images/2014/09/ibex-rule-forest-specific.png" />
</figure>

Here is a demo showing the forest propagation randomness:

<iframe width="100%" height="480" src="//www.youtube.com/embed/V_enCKx8XHA" frameborder="0" allowfullscreen="allowfullscreen"></iframe>

### Drawing into the world

**Drawing into the world is also done in GLSL: through uniforms.**
Another alternative way to do that would have be to use `gl.readPixels` to extract it out in JavaScript,
to write into the Array and inject it back to the shader...
but this solution is not optimal because `readPixels` is blocking and costy (CPU time).

```glsl
uniform bool draw; // if true, we must draw for this tick.
uniform ivec2 drawPosition; // The position of the drawing brush
uniform float drawRadius; // The radius of the drawing brush
uniform int drawObject; // The element to draw


void main (void) {
  ...
  bool prevIsSolid = CC==E||CC==G||CC==V||CC==S;

  if (draw) {
    vec2 pos = floor(p);
    if (distance(pos, vec2(drawPosition)) <= drawRadius) {
    // Inside the brush disc
      if (drawObject == W) {
        // Draw Water
        if (prevIsSolid && CC!=G) {
          // Source is drawn instead if there was a solid cell
          r = S;
        }
        else if (!prevIsSolid && mod(pos.x + pos.y, 2.0)==0.0) {
          // We draw Water half of the time because Water is destroyed when surrounded by Water
          r = W;
        }
      }
      else if (drawObject == F) {
        // Draw fire or volcano if solid cell.
        r = prevIsSolid ? V : F;
      }
      else {
        // Draw any other element
        r = drawObject;
      }
    }
  }

  ...
}
```

## World generation is also a Cellular automaton!

The world is generated on the fly when the ibex progress to the right. This is done chunk by chunk.

> More precisely, the world height is 256 pixels and a new part of the world is discovered each 128 pixels –
> In other words, the generation is divided into world chunks of `(128 x 256)` pixels.

Each world chunk is generated using a cellular automaton (different from the simulation one).

As shown in a previous example,
we can easily generate "cave like maps" from [this technique][cavelikegen].
I've added to this a [few improvments](https://github.com/gre/js13k-2014/blob/master/src/index.js#L842):

- The [initial random conditions](https://github.com/gre/js13k-2014/blob/master/src/index.js#L881) ensure
  that **the bottom of the world is Earth** and that **the top of the world is Air**.
  _(that with gradients of randomness)_
- [Randomness](https://github.com/gre/js13k-2014/blob/master/src/index.js#L896-L906)
  has been added to the rules to make the terrain evolving a bit more
  _(otherwise it creates stable but small caves)_.
- The number of generation step is set to 26. the randomness of the rules is decreasing through steps to produce stable results.
- In an attempt to create **seamless maps**,
  the initial random state for x=0 is set to the values of x=127 of the previous world chunk.
  [(code here)](https://github.com/gre/js13k-2014/blob/master/src/index.js#L878)
  It isn't perfect because you can still notice some edges.
- For **more diversity in generated chunks**, here are the parameters that can [randomly vary](https://github.com/gre/js13k-2014/blob/master/src/index.js#L845-L848):
  - The **amount of Earth** (can create dense areas VS floating platform areas)
  - The **chance of Water Source** in the Earth (will creates a lot of forest)
  - The **chance of Volcano** in the Earth (dangerous world chunk)

![](/images/2014/09/ibex-gen-variety.png)

## More articles to come

Did you like this article?

I'll try to write more about these subjects:

- The **"Pixels paradigm"**, Pixel as first class citizen: How to query and analyze the pixels world. How to do simple bitmap collision detection.
- The **game rendering performed in a GLSL shader** and all the graphics details I've spent hours on.
- **things I've learned from WebGL**, how to solve the bad approaches I've taken,
  and how I could have made a much more efficient game.
- **what could have made this game even more interesting**,
  and some ideas that was not reachable in a 2 weeks deadline.

IBEX is my game made for js13kgames. This article explains how the game has been implemented with GLSL and cellular automata.

Cellular Automata in IBEX

[js13kgames]: http://js13kgames.com/
[submission]: http://js13kgames.com/entries/ibex
[github]: http://github.com/gre/js13k-2014
[cellular]: http://en.wikipedia.org/wiki/Cellular_automaton

<a href="http://js13kgames.com/entries/ibex">
  <img src="/images/2014/09/ibex.png" alt="" class="thumbnail-left" />
</a>

**I've just [finished and submitted][submission] my game for [js13kgames][js13kgames],**
a contest where you have to make a web game in less than 13 kilobytes of a ZIP archive.

**[PLAY IT HERE][submission]** / [github][github]

**I had a lot of fun making this game and I think it is by far the best game I ever finished.**
It is a bit a continuation of my ["antsim" game](/2014/05/ld29) prototype in the idea
that you don't control directly the entities but you are at an higher level with simple interactions.

The game should be performant enough but however
require that you have a good hardware to support WebGL and some advanced limits (I used too much uniforms).
I'll talk more about the compatibility and performance issues in a next postmortem article.

If it doesn't work for you, please report me a dump of [http://webglreport.com/](http://webglreport.com/).

## Playthrough

<iframe width="100%" height="440" src="//www.youtube.com/embed/nqD2qIy4auU" frameborder="0" allowfullscreen></iframe>



## The Story

The world is burning, Protect and Escort a group of wild ibex away from the inferno.
On the path there are sleeping ibex to rescue, wake them and they will join the group.

## The Gameplay

You will have to use the **4 elements (Air, Earth, Fire, Water)**
to make the ibex progress safely in the environnment.

The 4 elements are primary elements but there are also secondary elements at play:

- The **Volcano** (creates fire)
- The **Source** (drops water)
- The **Forest** (created by Earth and Water)
- The **Wind** (left wind and right wind is created randomly in Air)

All elements interact with each other and **the ibex also react to elements in different ways**.

- Earth is a platform for the ibex
- Fire scares the ibex
- Water attracts the ibex
- Forest makes the ibex running faster

## The Controls

SPACE to draw an element, ARROWS to move, W/Z + X + C + V to switch between Air + Earth + Fire + Water.

Keyboard is recommended but playing only with mouse is also possible (click on elements and DRAG the inner cursor).

## Some technical notes

This game uses a [cellular automaton][cellular] to simulate a world with different elements (Air, Earth, Fire, Water).
This cellular automaton is technically computed as a texture in the GPU through WebGL and a GLSL shader (`logic.frag`).

While I was writing this game [@42loops](https://twitter.com/42loops) made me buy this awesome book that I'm still reading:

<blockquote class="twitter-tweet" lang="fr"><p><a href="http://t.co/8SiMZ9PWDX">pic.twitter.com/8SiMZ9PWDX</a></p>&mdash; greweb (@greweb) <a href="https://twitter.com/greweb/status/506862098597834752">2 Septembre 2014</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

You can interact with this world by drawing elements with a brush.

However, simulation is not enough to make a game so I mainly focused on the story and the gameplay:
On top of this simulation are living the ibex. They are managed in JavaScript and behaves with an AI.
The pixels collision and the ibex decisions (e.g; react on fire nearby) is based on querying the simulated world (stored in the GPU as a texture).

The rendering of the game is also performed in WebGL through another shader (`render.frag`).
My source code is [on Github][github].

**I will try to write a technical post-mortem to explain you more of this
and also what went wrong and what could have been more efficient in my usage of WebGL.**

## Bonus

During my early development, I've experimented the fire propagation in deep forest:

<iframe width="480" height="440" src="//www.youtube.com/embed/YU_pYAauFo4" frameborder="0" allowfullscreen></iframe>

IBEX is a game made in 13k of JavaScript code made for the js13kgames one-month contest.

IBEX, my js13k game

[ludumdare]: http://ludumdare.com/compo/
[play]: http://greweb.me/ld29/
[source]: //github.com/gre/ld29/
[entry]: http://www.ludumdare.com/compo/ludum-dare-29/?action=preview&uid=18803
[sunvox]: http://www.warmplace.ru/soft/sunvox/
[wrong]: /2014/05/ld29/#wrong
[right]: /2014/05/ld29/#right

<img class="thumbnail-left" src="/images/2014/05/computer_preset.jpg" alt="">

I **gamejam-ed** last weekend to the [Ludum Dare][ludumdare]
theming _"Beneath the Surface"_ (29th edition).

I enjoyed that time a lot.
What changed from the previous Ludum Dare for me is that
**I'm now** —and happy to be— **a father**,
and I'm enough trained to wake up at 3am so I could be there attending the beginning!

This article is my diary of this incredible 48 hours past to
develop **"Anthill", a minimalist anthill simulation game**.
This postmortem will explain what [went right][right] and what [went wrong][wrong]
for this compo.

# The Game

I haven't played any Ant Simulation Game
but I recently played a lot ["Banished"](http://www.shiningrocksoftware.com/),
an awesome city-building strategy game,
and I was inspired by the "assign jobs to people" gameplay of this game.

- **[Play the Game][play]**
- [Ludum Dare entry][entry]
- [Source code][source]

<iframe width="640" height="360" src="http://www.youtube.com/embed/DBt-5Qmzu1k?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

# Timelapse

Developing a complete game in 48 hours (including sleeping) is tough,
especially that it is also about making the graphics and the music!

The game resulting of these 2 days is more a **prototype** than a finished game:
the simulation remains minimalist and fastly boring,
the food is the only resource you have to care about.

Here is a **300x accelerated screencast of the developement of "Anthill"**:

<iframe width="640" height="360" src="http://www.youtube.com/embed/VhH7of4gAHk?feature=player_embedded" frameborder="0" allowfullscreen></iframe>



## <a name=right></a> What went right

### Music

Best achievement of my LD entry was –to me– **making the music**.

<img class="thumbnail-left" src="/images/2014/05/music_preset.jpg" alt="">

I'm not a musician, neither a pianist, but I played a lot with [Audio](/tags/audio/) the past year and I've managed to make a music for this game —and had a lot of fun making it.
I've used my _Yamaha P105_ as a MIDI controller for making the game music and connecting it
to [SunVox][sunvox], a modular tracker software.

#### Play the music - feedback appreciated

<iframe width="100%" height="450" scrolling="no" frameborder="no" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/playlists/32426683&amp;auto_play=false&amp;hide_related=false&amp;visual=true"></iframe>

<img class="thumbnail-right" src="/images/2014/05/playing_midi.png" alt="">

Most of the notes you heard have been **recorded live from my hand**, and I was quite proud of that, because I'm quite a noob on a piano.
Doing that way, you keep some imperfection in the music (little delay on the notes, especially in the intro music) and I think that sometimes makes the music better.

I've talked a few times about SunVox, also [I still want to make my own web version](/2013/07/zound-live/)
of a **modular audio tracker** that anyone (first myself!) could use
and also could embed live in the game (and, for instance, having game variable impacting the audio experience).

### Graphics

Also, I'm more a developer than a graphist so I would say this was a success^^

<blockquote class="twitter-tweet" lang="fr"><p>My best <a href="https://twitter.com/search?q=%23gamedev&amp;src=hash">#gamedev</a> graphics ever! <a href="http://t.co/FksRoq1r9x">pic.twitter.com/FksRoq1r9x</a></p>&mdash; greweb (@greweb) <a href="https://twitter.com/greweb/statuses/460558902812086272">27 Avril 2014</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

### Using a library

I've entirely **focused on making my game** rather than making the technical stack.
Usually, I tend to develop my own framework with the game.
It is good to learn and discover some [cool ways of programming a game](/2014/01/promisify-your-games/)
but this time I really wanted to get things done...

### Phaser.io

...so I've used **[Phaser](http://www.phaser.io/)** which is a trendy and awesome framework.
It is also built on top of the **Pixi.js** rendering library (I used in [LD27](http://www.ludumdare.com/compo/ludum-dare-27/?action=preview&uid=18803)) and **p2.js** physics engine,
which are two brillant and performant JavaScript libraries.

Hopefully I started my project with a "Phaser template" I bootstraped during the previous warmup weekend.
I've still lost some time playing with the Phaser API but I could have relied on Phaser features and performance so I think it worth it the second day.

### Google Hangout with Ludum Dare friends

I used Google Hangout during the whole Ludum Dare, as a way to put my webcam in the timelapse,
but more importantly to have other Ludum Dare friends coming in it!

This was a cool first experiment as an alternative to the "stream my dev" approach.
It was quite fun and social to have [@mrspeaker](http://twitter.com/mrspeaker)
showing me his crazy Metal Meter game advancement.

![](/images/2014/05/hangout.png)

## <a name=wrong></a> What went wrong

### Achievability

**My [initial plan](https://github.com/gre/ld29/blob/master/TODO.md) was too ambitious.**
It seems to always happen with me: I get the first day a lot of ideas and motivation, and I tend to underestimate the work to be done. Then at the end of the first day, I'm frustrated to find out I won't have enough time to do all my plans.
Indeed it is good to have a lot of ideas but, next Ludum Dare, I'll try to be sure to have achievable goals.

> Next time, let's **remove half the features** I establish!

So, the second day morning, I've been replanning from scratch and reprioritize my features to basically have something finished and working as a game.
Because of this decision, the result you can see is a game, but far from the one I originally wanted.
**This version is only about digging, collecting mushrooms and avoiding stravation**.

Also I originally scheduled to work that way **Day 1: developing-only, Day 2: music and graphics + new features**. I'm not sure this approach can really works, especially it doesn't scale, we better work by adding complete features one after the other. That theorically works, but it is however difficult to apply in practice with the stress of the Ludum Dare countdown!

### Path finding performance

**Implementing my own path finding algorithm was fast but not optimal** at all because of performances!
I recently released a bugfixed version which just use an existing [path finding library](http://qiao.github.io/PathFinding.js/visual/) to fix my bad implementation
and also to avoid an ant to request path finding each frame when looking for a task to be affected on.

### Finding the good simulation parameters

I underestimated a bit the amount of work needed to find the good parameters of the simulation.
Those are very important to **make the game well-balanced** (e.g. not impossible but also not super-easy), I don't think I found the optimal parameter in the released version.

I think I need two important things to make this parameter search easier:

- a framework to maintain parameters presets and change them live.
- make the simulation running at any speed to ease the development. (faster simulation)

### [bug] A task is not always completed by the closest ant

There is a inconvenient **proximity bug** in my game that you may have noticed:
when a new job is created, it may happen that, even if a ant was here nearby, a very far ant is assigned to this job.

I'm using a `foreach ant in noJobAnts { findAntTask(ant,availableTasks) }` loop.
In this first approach, even if a ant will take the closest task in `findAntTask`, the first assigned ant will occupy the task even if a closer ant was after in the noJobAnts list.

Another approach to solve this issue would be to do `foreach task in availableTasks { findTaskAnts(task,noJobAnts) }`.
In this second approach, the `findTaskAnts` should sort the noJobAnts list for the given task proximity.

However it is not that trivial because tasks also have different priorities for a given ant, and `findAntTask` solved that.
In my original plan, there is some basic tasks like "clean the dirt" or "clean the corpse" which can be done by any ant. However, a specialized ant (let's say an Harvester) may have some more important tasks to be done first, so this is why we need this priority.

In other word, fixing this bug is not trivial and I need to find the optimal loop for that!

## To be continued...

I really wish to continue this game because I enjoyed making it and I would enjoy playing the one I have in mind!
Time will tell if I can accomplish that wish!

![](/images/2014/05/anthill.png)

## You can make games!

I strongly think anyone a bit motivated and inspired can participate [Ludum Dare][ludumdare].

Whoever you are, you can make games!

- If you are a developer, you can develop games easily! But that's not enough, you will require graphics and music!
- If you are a graphist, you can make crazy beautiful games! There is tools to help you making the game without coding.
- If you are a game designer or story teller, you can make awesome games too! You could also just make a cool text adventure game?

<iframe width="640" height="480" src="//www.youtube.com/embed/PVbCECjxFds" frameborder="0" allowfullscreen></iframe>

I gamejam-ed last weekend to the Ludum Dare 29 theming "Beneath the Surface" to develop "Anthill", a minimalist anthill simulation game.

48 hours to prototype an Ant Sim Game

[demo]: http://js1k.com/2014-dragons/demo/1790
[source]: https://gist.github.com/gre/9504494
[jscrush]: http://www.iteral.com/jscrush/
[jscrush-npm]: https://github.com/gre/jscrush/
[demojs]: http://demojs.org/
[js1k]: http://js1k.com/
[p01]: http://www.p01.org/

[<img src="/images/2014/03/js1k.png" alt="" class="thumbnail-left" />][demo]

This article introduces my journey into the JS1K world
and a few tricks I've used for my entry ["Panzer Dragoon 1k"][demo] ([source][source]).

Welcome to the world of hacks, tricks and getting-things-done-at-any-price.
You will turn the worst JavaScript practices and ugliest JavaScript facts to your advantage.
Welcome to the world where coding the bad way is satisfying!

## Panzer Dragoon 1k

- **[Play the JS1K entry][demo]**
- [Source Code][source]

## Panzer Dragoon Original Game

<iframe width="640" height="480" src="//www.youtube.com/embed/peoRBj9U-jI" frameborder="0" allowfullscreen></iframe>



# JS1K

**[JS1K][js1k]** is a competition where you have to make a demo (or a game, or anything)
in less than **1 kilobytes** of JavaScript: **less than 1024 characters of source code**.

To reach that goal you will need ideas, JS ninja tricks
and most important: **patience and perseverance**!
But really, **anyone can participate**.

I recommend that you take a look at [js1k.com][js1k] and browse the existing entries.
There is awesome guys participating to this yearly event,
I had the chance to meet some of them at [DemoJS 2013][demojs] Paris event.
Also checkout [www.p01.org][p01] which contains some very good examples of crazy short demos.

## Tools

But first things first: you need tools to minimize source code (it can simply be removing comments and spaces, minifiers, or it can be much more crazy tools like crushers).

Personally, I'm using:

```bash
cat source.js | uglifyjs -c unused=false | tee minified.js | jscrush > crushed.js && wc -c *.js
```

This small homemade command (to use in a npm script) results for my game in:

```
    1019 crushed.js
    1756 minified.js
    7241 source.js
```

If you are interested, I've made this toolkit available in a complete boilerplate
that you can easily fork for your own usage:
[https://gist.github.com/gre/9364718](https://gist.github.com/gre/9364718).

> **P.S.** [`jscrush`][jscrush-npm] is a npm module that you can directly use from the CLI
> but it is a port of the awesome [www.iteral.com/jscrush/][jscrush].

# The beginning: Saving bytes

It quickly becomes frustrating to compete in JS1K
because you are basically trying to put a cow in a car (or an elephant if you are ambitious!).
But this frustration actually becomes addictive!

**Saving bytes** is your job - once you get your first working prototype, and inevitably blow your byte limit.

When you reach that limit, a good idea is to practice an **"add feature -> remove code"** development loop
that really makes you think hard about your ultimate goal, and helps improve your entry.

> **The JS1K-based development:**
> Adding more and more features,
> figuring out how to fill everything in,
> re-thinking your demo to only keep the essential features.
> This will keep making your demo better.

You have to make a very hard choice: **_Which feature to remove?_**
It is all about budget, not in term of money but in term of bytes!
A bit like in daily life: making choices with limited resources!

## JSCrush

**_JSCrush_** is a crazy tool you may want to use to go deeper in the bytes reducing.

It basically implements a compression algorithm which is based on substring occurences.
The challenge of such a tool is not only to make a good compression but to make
a very small decompressor embedded in the result code because
this decompressor might be an overhead _(~ +60 bytes with small code)_.

If you are using _JSCrush_ which I recommend for saving extra bytes,
you may want to use some tricks to go even further with it!

The first time, you usually can save about 20% of bytes with classic 1k minified code.
But if you optimize your code **for** _JSCrush_, you can save much more!
I've achieved about a 40% code reduction in my demo!

Most of the tricks is about finding code patterns (same succession of JavaScript source code characters)
and trying to duplicate them.

When I say **duplicating code**, it is really about **DUPLICATING code!**

> Once "indexed", a duplicated code is likely to just take one more byte in the final crushed JavaScript!

# Some tips and tricks

[<img src="/images/2014/03/js1k_2.png" alt="" class="thumbnail-right" />][demo]

This section will share with you a non-exhaustive list of tricks.
I'm not going to talk so much about the basic and classic ones,
but a few novel ones that I found to work well in my entry.
You may prefer to directly read the [annotated source code of "Panzer Dragoon 1K"][source] instead!
Of course, most of those tricks work closely with the `| minify | jscrush` transformation.

> Careful! Some tricks might be counter-intuitive as first glance,
> again it ties-in with the way JSCrush is working.

## Reduce your language

All existing functions and properties are costly in bytes,
each time you use another one, it definitely add bytes.
To save bytes, you have to limit your set of functions/properties to use
or find ways to access them indirectly.

- **Use as few variables as you can**: this is valid in computer science in general: the best systems are those with the fewest possible variables (states). if one variable can be computed out of others, it should be removed. Also consider allocating some temporary variables to re-use like in an assembly registry (e.g. `i`, `j`).
- **Reduce the set of functions** you authorize yourself to use! You may just need to use "fillRect" for everything, or "arc". Also don't use both `Math.min` and `Math.max`, one can be implemented with the other.
- **Minimize the different values / colors** you are using (most of the time digits are fine, but `#RGB` colors are costy).

## Duplicated wins!

- Generally: try to **duplicate the exact same code everywhere**!

- **Do not use explicit aliasing** like `M=Math` and `C=M.cos`, JSCrush does that job for you.
- **Get rid of intermediary computation.** Prefer inline and duplicated computation over variable assigment.
- Also, `a*(b+c)` might be more bytes than `a*b+a*c` if `a` is an expression. (but doesn't work in all cases)

**A few examples:**

```javascript
a = b + c;
translate(a, a); // NOPE!
translate(b + c, b + c); // YES!
```

```javascript
size = a + b + 10;
fillRect(x - size, y - size, 2 * size, 2 * size); // no please don't!
fillRect(
  x - (a + b + 10),
  y - (a + b + 10),
  2 * (a + b + 10),
  2 * (a + b + 10)
); // YEAH!
```

```javascript
fillRect(10,10,20,20);
...
fillRect(9,9,18,18); // Can you afford to use 10,10,20,20 instead?
```

In my demo, I was able to factorize some code. For instance the way I draw and update the x,y of my opponents and particles are the same duplicate chunk of code:

```javascript
bga();
arc(
  // Update
  (e[0] += e[3]),
  (e[1] += e[4]),
  e[2],
  0,
  9
);
fl();
```

- You sometimes can **save bytes by adding more code**! For instance, if you need `fillStyle` and `strokeStyle`, it may save bytes to always set both color at the same time! `fillStyle = strokeStyle = ...` even if you only need once.
- Always **use the same `function parameters`**. In my game, I use `function(e){` everywhere even if I don't use that `e` in all my functions. This is saving a bunch of bytes with JSCrush.
- **Here's a particularly crazy trick:** If you have different collections of complex objects, you can simply represent each item by a vector (an array) and figure out how you can make use the same indexes for the use-case.

In my game:

```javascript
o = []; // an opponent: [ 0: x, 1: y, 2: health, 3: vx, 4: vy, 5: locked, 6: hitTime ]
p = []; // a particule: [ 0: x, 1: y, 2: size,   3: vx, 4: vy, 5: damage ]
```

- You also may find better way of managing collections. Instead of using `t.push(o)` to add, `t.splice(i, 1)` to remove, and `for(i=0;e=o[i];i++){...}` to iterate. I am using `t[Math.random()]=o` to add, `delete t[i]` to remove and `for(i in o){ e=o[i]; ... }` to iterate. It saved a lot of bytes if you already use `Math.random()` somewhere else! For-in loops are also quite short and can by used for other tricks (e.g. _Programmatical aliasing_).

<blockquote class="twitter-tweet" lang="fr"><p>My <a href="https://twitter.com/search?q=%23js1k&amp;src=hash">#js1k</a> uses `t[Math.random()]=insert`, for-in loops and `delete t[i]` rather than push and splice. Saving bytes with jscrush</p>&mdash; greweb (@greweb) <a href="https://twitter.com/greweb/statuses/439324052403277824">28 Février 2014</a></blockquote>

- Use just **one letter variable names** (mangling variables won't work because they are in window scope, and IMHO it is better for you to write them by hand)
- You will probably need to **initialize some variables**, but do it only if necessary (if you have `ReferenceError`) and **use the multi-assignment syntax**: `A = B = 0` if you can. You should never have constant variables, it saves bytes to directly use the value inline.
- **`with(c){ ... }`** in your main loop may save bytes. It makes all functions and properties of c (the drawing context) in the scope.

## Language tricks

- **Never use `var`**, just put everything in `window`
- **Programmatically aliasing `c`'s method** may save you a lot of bytes (or may not, you have to check!). You also have to find the code which suit the best your use case. Be careful about collision. Here is mine: `for (e in c) c[e[0]+e[2]+(e[6]||"")] = c[e];`
- Do not waste ANY value returned by assignment and operators (i++, x=.., x+=...). I'm sure you can do it somewhere else!
  Typical example:

```javascript
x += vx;
y += vy;
/* ... */ fillRect(x, y, s, s); // NOPE!
/* ... */ fillRect((x += vx), (y += vy), s, s); // YES!
```

- Try to not separate update from drawing logic. Mixing them may save bytes.
- You don't want to use `addEventListener`, just define listeners straight on window! e.g. `onclick = function(){...`

## Make your JS1K now!

[<img src="/images/2014/03/js1k_3.png" alt="" class="thumbnail-left" />][demo]

I'm really eager to see all JS1K entries
because I usually enjoy reading people's code and
especially all the crazy tricks that I can learn from your code :-)

This article was just sharing a bunch of tricks which work for my entry,
but you will find much better tricks for your demo -
so please do it and make your crazy work!

---

_Special thanks to [@mrspeaker](http://twitter.com/mrspeaker) for fixing my English_.

Panzer Dragoon 1k is a 2D remake of Panzer Dragoon in 1k of JavaScript I made for JS1K 2014

Panzer Dragoon 1k

[promise]: /2013/07/q-a-promise-library/
[ld]: http://www.ludumdare.com/compo/
[game]: http://greweb.me/ld28/
[qimage]: https://npmjs.org/package/qimage
[qajax]: https://npmjs.org/package/qajax
[submission]: http://www.ludumdare.com/compo/ludum-dare-28/?action=preview&uid=18803
[zanimo]: https://github.com/peutetre/Zanimo
[npmjs]: https://npmjs.org/
[github]: https://github.com/gre/ld28
[app.js]: https://github.com/gre/ld28/tree/master/src/app.js

One month ago was the [LudumDare][ld] #28 gamejam theming _"You Only Get One"_.

<a href="http://greweb.me/ld28/">
  <img src="/images/2014/01/ld28.png" alt="" class="thumbnail-left" />
</a>

I [submitted][submission] a [mini-game][game] which ranked 105th out of 2064 entries and also 26th in the "theme" category.

This is of-course a web game implemented in JavaScript and using HTML and CSS.

But actually, my main goal was not really making a game done
but more about technically **making a state-of-the-art Promise-based game**.

I think [Promises][promise] contains very interesting advantages in a game development design:
_Resource loading managment_, _game scenes chaining_, _animations_... are some use-cases.

- Checkout the [source code][github] on Github - [`src/app.js`][app.js] is the entry point
- LudumDare entry is [here][submission].
- [Play the Game][game].



## FP in game development

Using some Functional Programming paradigm in game development is interesting,
and here I'm just talking at least about the basic stuff:
**Avoid globals, Minimize state variables**.

I've written a few games where restarting the game without using `location.reload()` was a challenge
because the game variable states was so spread everywhere!

By doing more FP, you can have this restart feature by design without need to "reset" all variables
because your start function just takes everything it needs in parameter and restarting is just about re-calling that function.

## Promises as first-class citizen

### Game scenes chaining

Like maybe 99% of games, my game has an **intro** (menu), a **main** scene and an **outro** scene (gameover / finish).

When you develop a game with just one big `render()` loop,
it easily becomes a pain when you want to add more steps to the scene,
it doesn't scale and fastly become spaghetti code:
you tend to have to figure out in which state you are (or which part of the animation timeline) from the game state.

Hopefully, scene management is very easy to do with Promises:

```javascript
function start() {
  return Q().then(intro).then(_.partial(runMiniGames, 20)).then(outro);
}

Q.all([
  /*..something to load..*/
])
  .then(start /*, ..*/) // start game when ready
  .done(); // just help Q to trigger errors if some.
```

How beautiful to read! Call `intro` then run 20 mini-games then perform `outro`.

#### No game state shared, pure functions

**intro** is the menu screen where you can choose the game difficulty.
**outro** is the game end screen where the final score is displayed.
There is however **no global variables shared**, those are just passed from one function to another.

Let's look deeper in how it works:

- The `intro()` function just returns a Promise resolved when the user made a "difficulty" choice. That Promise actually contains the difficulty (0, 1 or 2).
- The `runMiniGames` function takes 2 parameters: the number of games and the difficulty. `_.partial(runMiniGames, 20)` is just an helper for making a 20 mini-games function which takes the difficulty in parameter. This difficulty is given by the previous Promise. The `runMiniGames` function returns a Promise of Score (integer).
- That score is then fed into the `outro(score)` function which displays this score to the user.

> **TL;DR.** This is just about plumbing 3 functions together!

Checkout also the [`runMiniGames` implementation](https://github.com/gre/ld28/blob/master/src/app.js#L24-L37).

#### Speed up the development

And you know what? It make development easier and faster because you can easily skip some part in any Promises chain:

```javascript
function start() {
  return (
    Q(0)
      //.then(intro) // Directly jump to the games
      .then(_.partial(runMiniGames, 20))
      .then(outro)
  );
}
```

I used that a lot and not only for this part, but for all part during the game development.

### Loading resources

Promises also help you to wait resources before starting the game.
You don't have to make yet another loading library, Promise already are ready for that,
and you can also have proper error managment or even "progress" loading display (Q has Progress event in a Promise).

Each loading resource is a Promise and you can combine them all using `Q.all`.

Here is an example using [Qajax][qajax] and [Qimage][qimage].

```javascript
Q.all([
  Qajax("music.wav").then(mapToAudio),
  Qajax.getJSON("map.json"),
  Qimage("images/logo.png"),
  Qimage("images/textures.png"),
]).spread(
  function (music, map, logo, textures) {
    // Start the game !
  },
  function (error) {
    // display proper error
  },
  function (progressEvent) {
    // maybe you want to display a loading progress bar
    // with that third progress callback.
  }
);
```

Here is a similar example:

```javascript
var musicPromise = Qajax("music.wav").then(mapToAudio);
var mapPromise = Qajax.getJSON("map.json");
var texturesPromise = Qimage("images/textures.png");
Q.all([mapPromise, texturesPromise]).spread(startGame, errorLoading);
// because maybe you don't want to wait the music for starting the game:
musicPromise.then(function (a) {
  a.play();
});

function startGame(map, textures) {
  // ...
}
function errorLoading(e) {
  // ...
}
```

### Mini games workflow

My games is divided into a set of mini-games which are all independent but share a common interface.
This interface was quite a WIP at the end of the weekend development but it does the job.

Here is the template I used for my game: [src/games/\_template.js](https://github.com/gre/ld28/blob/master/src/games/_template.js).

A Game instance has different methods, and especially `enter` and `leave` method which are call on game enter and on game leave. It also has a `.end` Promise which is resolved when the Game end.

- A mini-game when solved gives a score depending on how well the user succeed it (through the `end` Promise).
- A mini-game have a timeout and if the player doesn't terminate it, it passes to the next game without scores.

Those `enter()` and `leave()` methods return Promise in order to be plugged in the game workflow (we can wait them to finish before moving to next state).

For instance, we don't start the game timeout before it actually starts (just wait the `enter()` Promise to be resolved) and also we don't switch to the next game before the `leave()` Promise is done).

Checkout also the [`nextMiniGame` implementation](https://github.com/gre/ld28/blob/master/src/app.js#L51-L76).
The result of that function is the score of the mini-game and that we sum up all scores from the previous score.

#### Composability

The `enter()` and `leave()` methods can be composed of animations which can themselves be composed of animations.

**We can easily subdivided work into different level of Promises chain.**
Here is a little schema to summary that composability:

![](/images/2014/01/ld28_composition_schema.svg)

### Promise Animations

In my game, all the animations are controlled with Promises more exactly using CSS3 Transitions
via **[Zanimo][zanimo] Promise library** because it fits my game (DOM-based game).
The fact that a Promise can be waited and chained **gives a powerful controls over CSS Transitions for making animations**.

You can easily trigger animations **one after another** for moving an element in multiple places.
You can also perform **multiple animations at the same times** (on 2 different elements) and **wait for both to finish**
before triggering a third animation.

See for instance how `enter()` and `leave()` animations are done in mini-games.

In the animation ending the "memo" game I used concurrent animations:
all memo cards are randomly moved out.

```javascript
/* // FYI
Card.prototype.transform = function (x, y, scale, duration) {
  return Zanimo.transition(this.el, "transform",
    "translate("+x+"px, "+y+"px) scale("+scale+")", duration||0);
};
*/

function animateOut(dispersion) {
  return Q.all(
    _.map(cards, function (card) {
      if (card.destroyed) return Q(); // no animation because card is destroyed
      return Q()
        .then(function () {
          return card.transform(
            card.x,
            card.y,
            card.number === 1 ? 1 : 0.8,
            100
          );
        })
        .delay(Math.floor((card.number === 1 ? 500 : 0) + 300 * Math.random()))
        .then(function () {
          var x = Math.round(
            (Math.random() < 0.5
              ? -card.w / dimensions.width - dispersion * Math.random()
              : 1 + dispersion * Math.random()) * dimensions.width
          );
          var y = Math.round(
            (Math.random() < 0.5
              ? -card.h / dimensions.height - dispersion * Math.random()
              : 1 + dispersion * Math.random()) * dimensions.height
          );
          return card.transform(x, y, 0, 500);
        });
    })
  );
}

// Usage in Memo.leave() :
return Q.delay(50)
  .then(function () {
    return animateOut(0.5);
  })
  .delay(100);
```

In the calculation game I used a chain of animations subdivided in functions:

```javascript
return Q.delay(50)
  .then(fadeOutInvalids)
  .then(displaySolution)
  .then(displayEquality)
  .delay(500)
  .then(fadeOut)
  .then(hideEquality)
  .delay(200);
```

[Full code here](https://github.com/gre/ld28/blob/master/src/games/calculation.js#L411-L500).

### "Wait for next click"

While my game are just based on click user interaction,
I've made a [`waitNextClick`](https://github.com/gre/ld28/blob/master/src/waitNextClick.js) function
which returns a Promise of click for the given element.

```javascript
var Q = require("q");

module.exports = function waitNextClick(btn) {
  var d = Q.defer();
  btn.addEventListener(
    "click",
    function listener(e) {
      btn.removeEventListener("click", listener);
      d.resolve(e.target);
    },
    false
  );
  return d.promise;
};
```

This was quite an interesting solution which is just like a jQuery "once" event but in Promise paradigm.

I was able to combine that function with `Q.race` which wait for one of the given Promise to be redeemed.

> `Q.race(_.map(btns, waitNextClick))`

For instance in the cats game, I just wait the first "This one" button to be clicked:

```javascript
var houseChoice = Q.race(_.map(this.houses, function (catHouse) {
    return waitNextClick(catHouse.btn)
    .then(function () {
      return catHouse;
    });
// houseChoice is a Promise of House choosen by the player.
```

### Using the "progress" event

I also used a bit the "progress" event of a Q Promise, which is a way to notify that a Promise is being resolved.

- I used that "progress" event on the `game.end` Promise for notifying that the player is winning some scores in a mini-game while playing.
- I also used it to make a timeout ticking the remaining time before the timeout is reached and that Promise resolved.

See both usages [here](https://github.com/gre/ld28/blob/master/src/app.js#L62-L70):

```javascript
return Q.race([
  gameEnd.progress(function (score) {
    stats.setScore(totalScore + score);
  }),
  timeoutWithTicks(gameEnd, timeout)
    .progress(stats.setTimeProgress)
    .then(_.bind(game.submit, game)),
]);
```

## Code organization using NPM + Browserify

NPM & Browserify has also been used because I find this stack very productive,
especially when writing a game from scratch.

Browserify has been trendy the last past year, but there is here an interesting way of organizing your code
and especially reusing it.
You can find a lot of [available modules using NPM][npmjs],
Browserify will just make you able to require them using `require("modulename")`.

a game showcase using Q Promise as first-class citizen and driven with CSS3 Animations via Zanimo.

Promisify your games


[gamelier]: http://gamelier.org/gaetan-renaudeau-on-procedural-vs-functional-rendering/
[slides]: http://greweb.me/prez-functional-rendering

I've done a talk at **[Gamelier][gamelier]** last Monday about
how to think the **rendering** in a more **functional** way.

## Abstract

Most of today 2D graphics libraries restrict us to a set of primitive procedures (`drawRect`, `drawCircle`, `drawImage`,...) but when it comes to bring more interesting features you tends to be stuck with it. Let's see how we can just do things with a function of `(Vec2 => Color)`.

This is the way (_WebGL_) **GLSL** has already took and the presentation examples will be built on it.
Let's see what are the multiple benefits of taking that paradigm of rendering.

## Talk

<iframe src="//player.vimeo.com/video/78804695?title=0&amp;byline=0&amp;portrait=0" width="600" height="337" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>

### [Open the slides][slides]

## Checkout more presentations at Gamelier.org

[![](/images/2013/11/gamelier.png)][gamelier]


This talk explains how to think the rendering in a more functional way. Let's see how we can just do things with a function of (Vec2 => Color).

Functional Rendering


<a href="http://greweb.me/webaudioapi-introduction">
<img src="/images/2013/09/webaudioapiprez.png" alt="" class="thumbnail-left" />
</a>

<a href="http://greweb.me/webaudioapi-introduction">Open the presentation</a>
/
<a href="http://greweb.me/webaudioapi-introduction?azerty=1">AZERTY version</a>


A presentation overview of the Web Audio API

Slides: Web Audio API, Overview

While continuing to experiment with Web Audio API and GLSL, I've made a game called Timelapse for js13kgames (an HTML5 game competition where entries must be less than 13 kb zipped).

Making a rhythm game with bleeding-edge web

[webaudioapi]: https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html
[zenexity]: http://zenexity.com
[github]: http://github.com/gre/beez
[app]: http://beez.greweb.fr/
[webrtc]: http://www.webrtc.org/
[webrtcapi]: http://www.w3.org/TR/webrtc/
[websocketapi]: http://www.w3.org/TR/websockets/
[fm_article]: /2013/08/FM-audio-api
[playframework]: http://playframework.com/

<img src="/images/2013/09/beez.png" alt="" class="thumbnail-left" />

Here is **Beez**, a web real-time audio experiment
using smartphones as synthesizer effect controllers.

This is our second [Web Audio API][webaudioapi] experiment made in one Hackday at [Zenexity][zenexity] (now Zengularity).

This time, we were much more focused on having the best **latency performance**:
we used the bleeding-edge [WebRTC][webrtcapi] technology,
which allows you to link clients in Peer-to-Peer instead of a classical Client-Server architecture.

- [The project on Github][github]
- [Test it now!][app] (Chrome)

### Live demo of the Hackday application

<iframe width="640" height="480" src="//www.youtube.com/embed/QwU6IMNLF0o" frameborder="0" allowfullscreen></iframe>

_Bonus for the one who recognizes the melody :-)_



## The Experiment

The experiment consists in controlling an audio stream running on a desktop web page with
some audio effect pads running on phones via a mobile web interface.
**Our main goal was to make the best real-time experience.**

### Hive and Bees

An **Hive** is controlled by different **Bees**, eventhing connected in Peer-to-Peer (via WebRTC).

#### The Hive

The **Hive** is a web page where the sound is generated and visualized _(Web Audio API)_.
It also shows you in real-time the different effects XY pads and allows you to control them.

![](/images/2013/09/hive.png)

#### A Bee

The **Bee** is a mobile web page which allows you to control the different sound effects with XY pads.
It only works on Android Chrome now _(WebRTC required)_.

![](/images/2013/09/bee.png)

### Audio tech

We used [Web Audio API][webaudioapi] for generating the sound client-side on the Hive:

We have a note sequencer which plays a **_famous melody_** through a [Frequency Modulator][fm_article] and different other effects.
Some controls allow you to change the **BPM**, **gain** of the carrier and the modulator, **finetune**,
frequency **multiplicator** (0.25, 0.5, 1, 1.5, 2) of the carrier and the modulator,
**reverbation**, **filter** (frequency and resonance).
There is also a delay effect made on both left and right channels to produce a cool stereo effect.

That's quite basic audio stuff so far, I can't wait to experiment deeper and try to generate more complex sounds with that awesome Audio API.
Again, our main goal was to make a P2P connection between the hive and its bees.

### Network architecture

<img src="/images/2013/09/beez_arch.png" alt="" class="thumbnail-left" />
**Every bee are connected to the hive with a bi-directionnal Peer-to-Peer connection thanks to [WebRTC][webrtc].**

Everytime a (bee) user moves an effect controller with his phone, a position event is sent to the hive.

Basically:

```javascript
xyAxis.on("change:x change:y", function () {
  hive.send(["tabxy", this.get("tab"), this.get("x"), this.get("y")]);
});
```

_As you can see, we used Backbone.js models for events._

However, A lot of Touch events per second can be triggered by an Android device, and it may depends on the device speed. We shouldn't send to the network all of these events because it can saturate it and cause some lags. To avoid that we need to **throttle the touch events before sending the event to the network**.

This is done transparently with the [`_.throttle`](http://underscorejs.org/#throttle) function and we choose to **throttle by 50 milliseconds** which is **about 20 events per second** which is ok for human eye.

```javascript
xyAxis.on(
  "change:x change:y",
  _.throttle(function () {
    hive.send(["tabxy", this.get("tab"), this.get("x"), this.get("y")]);
  }, 50)
);
```

We use different other events:

- A bee can send `"tabxychanging"` and `"tabopen"` respectively to informs the cursor has been pressed/released and to inform a new tab has been opened.
- When a Hive receive a `"tabopen"`, it will send back to the bee a `"tabxy"` event in order to inform what is the current value of that tab so we can init the cursor to the current xy axis position on the bee interface.

## WebSockets vs WebRTC

<img src="/images/2013/09/websocket.png" class="thumbnail-left" />

Most "real-time" web experiments you see on the Internet today use [WebSockets][websocketapi].
WebSockets are good, it's a significant evolution from the Ajax years.

WebSocket is a protocol on top of TCP, which **links a browser with a server in a bidirectional text communication**.
Getting 2 clients to communicate generally consists in broadcasting messages from the server to all clients
(see the schema).

**This architecture has some advantages:**

- Simple to understand, Easy to use.
- We can easily implement some server validation.

**But also has some drawbacks:**

- Not always easy to traverse **proxies**. _(e.g. through an nginx front server)_
- Only text communication.
- **bandwith** intensive. _(all the bandwidth goes back and forth with your server)_
- **CPU** intensive. _(e.g. receiving 20 messages per second from 10 clients can be a lot for a small server, especially if you are doing some message processing)_

(The last two "cons" are scalability issues)

<hr style="clear:both" />

<img src="https://upload.wikimedia.org/wikipedia/commons/a/ac/Logo-webrtc.png" class="thumbnail-left" />

[WebRTC][webrtc] (_Web Real Time Communication_),
is a new web technology which helps to connect browsers in a **Peer to Peer** way.

WebRTC has been designed for transfering binary data like files, audio, video (e.g. a webcam stream).
Of-course, we can still use it for text.

<br style="clear:both" />

<img src="/images/2013/09/webrtc.png" class="thumbnail-right" />

Unlike WebSockets, multiple steps are required to **establish a P2P connection between two web clients**.
It is due to the fact that the two clients must resolve the closest network path to communicate with each other.
That resolving phase requires a communication between the clients, and for that we can use WebSockets as a _"Control Channel"_.

But once the two web clients are connected, they basically don't need the web server anymore and can **communicate directly together**.
If the two clients are in the same local network, they should directly communicate through that local network.
That **reduces the server load** and should significantly **decrease the latency**.

### Playframework / Akka Actors

[Playframework][playframework] has been used on the server side for making that WebSocket Control Channel,
and akka was convenient for handling peer communication and rooms management.

## About the melody

You still didn't guess where does the melody came from?

Well, here is the answer:

<iframe width="640" height="480" src="//www.youtube.com/embed/3rU_ei_x0Ag" frameborder="0" allowfullscreen></iframe>

## Awesome team!

Finally I want to thanks my team-mates: [@mrspeaker](http://twitter.com/mrspeaker), [@etaty](http://twitter.com/etaty), [@NicuPrinFum](http://twitter.com/NicuPrinFum), [@drfars](http://twitter.com/drfars), [@srenaultcontact](http://twitter.com/srenaultcontact)
with who we were able to make that demo from scratch in one day!

Here is Beez, a web real-time audio experiment using smartphones as synthesizer effect controllers. This is our second Web Audio API experiment made in one Hackday at Zenexity.

Beez, WebRTC + Audio API

[zoundarticle]: /2013/07/zound-live/
[zoundrepo]: http://github.com/gre/zound-live/
[zoundfm]: https://github.com/gre/zound-live/blob/master/app/assets/javascripts/modules/SimpleFM.js
[fmwiki]: http://en.wikipedia.org/wiki/Frequency_modulation_synthesis

The main principle of [Frequency Modulation (FM)][fmwiki] is to **pipe an Oscillator (the Modulator)
into the frequency of another Oscillator (the Carrier)**.

This article will explain to you how FM Synthesis works with **interactive demos**.
In the meantime, all demos are implemented with the brand new **Web Audio API**,
so feel free to hack the code for your own purpose.

This article will also introduce some Audio concepts like **LFO**, **Envelope** and **Finetuning**.

I've recently implemented a very first FM in [ZOUND live][zoundarticle] - _a HTML5 collaborative audio tracker_,
giving much more powerful Synthesizers (see in the following video).

<iframe width="640" height="480" src="//www.youtube.com/embed/El4JvaDWQUM" frameborder="0" allowfullscreen></iframe>
[*(here is the implementation of that FM)*][zoundfm]



## Dive into Frequency Modulation Synthesis

As mentioned previously, FM is about **piping an Oscillator (the <u>Modulator</u>) into the frequency of another Oscillator (the <u>Carrier</u>)**.

The Modulator oscillation only affects the oscillation frequency of the Carrier but is not directly an audio signal.

![](/images/2013/08/fm_principle.png)

The result of that modulation differs depending on each oscillator **frequency** and **amplitude**:

[![](/images/2013/08/Frequencymodulationdemo-td.png)](http://en.wikipedia.org/wiki/File:Frequencymodulationdemo-td.png)

**_N.B._** _Our interactive demos in this article will always play a sound and visualize it (waveform / spectrum analyzer).
You will have different kind of controls depending on each specific aspect I want to illustrate._

_The demos should work on Chrome. **However if you get an AudioContext failure, please reload the page** (you may not be able to start them all in one row)._

### LFO

**Low-Frequency Oscillation (LFO)** is very used in electronic music for making rythmic audio effects.

LFO is simply a specific subset of a oscillator in a sense that **its oscilation frequency is under
the human audible range (20 Hz)** and is then not generally used as an audio signal but as an effect controller.

For instance the frequency / the amplitude of an oscillator, or in the following example the frequency of the cut-off filter:

<audio src="http://upload.wikimedia.org/wikipedia/commons/e/e4/Lfo-cutoff-frequency-wobble-bass.ogg" controls></audio>

Now, as a first demo,
let's see what happens if our **FM Modulator is an LFO**,
_(i.e. if that Modulator is in low frequency range)_.

<iframe width="100%" height="310" src="http://fiddle.jshell.net/FvnJx/58/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/FvnJx/58/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

Observe in the Carrier graphs how **the waveform is regulary compressed and decompressed**. If you increase the Modulator frequency, it will speed up this effect. A real FM is about speeding up that effect up to the audible range...

**_N.B._** _With *Web Audio API* (more generally with any modular synthesizers) we can easily control any module parameter with an LFO:_

```javascript
lfo.connect(carrier.frequency);
```

#### Modulator in audible range

Now, if we increase the frequency to the hearing range, here is what happens:
_(in that example you can also change the Carrier frequency)_

<iframe width="100%" height="310" src="http://fiddle.jshell.net/x4CWR/36/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/x4CWR/36/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

It's as if that **once the Modulator reaches that audible barrier, it kind of becomes a second audible synthesizer**,
even if it only modulate the frequency of the actual synthesizer.
However, it's completely different than playing the two synthesizers directly into the output,
again the modulator influence the frequency of the carrier and is not directly piped into the output audio signal.

_There is especially cool sound produced when the Modulator frequency is closed to the Carrier frequency. For more infos, see the <u>Finetuning</u> section._

### Frequency ratios: harmonic or dissonant sounds

One thing you may also have notice in the previous example is that most of the generated sounds was quite dissonant, non harmonic.

Now, if we add more restrictions and only **snap the possible modulator frequencies**
to a **multiple of the carrier frequency**, here is what happens:

<iframe width="100%" height="310" src="http://fiddle.jshell.net/Euezv/17/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/Euezv/17/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

This harmonic result is due a simple fact in music: **Mutiplying a note frequency by 2 is equivalent to Increasing that note by one octave,** meaning the note has the same tone but is one-octave higher. (and vice versa for the division). _BTW, you may have noticed that fact by repetition of peaks in the previous example Spectrum Visualization._

Now we can release some restrictions by also allowing frequencies multiple of `carrier frequency / 4`, which means allowing to increase/decrease by an **octave**, a **semi-octave** or a **quarter-of-octave**.

<iframe width="100%" height="310" src="http://fiddle.jshell.net/DFSwN/13/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/DFSwN/13/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

_Eventually you could even allow more freedom using multiple of `carrier freq / 12`, because an octave is equally divided by 12 in the [Chromatic scale](http://en.wikipedia.org/wiki/Chromatic_scale)._

### Mixing the power of the Modulator effect

A very interesting part of the job is also to change the **amplitude of the modulator**. So far, we used a full amplitude modulating the carrier frequency from 0 to 2-times its original frequency which produces a quite rough sound.

Try to change the modulator amplitude on the following demo:

<iframe width="100%" height="310" src="http://fiddle.jshell.net/DAT5S/12/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/DAT5S/12/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

Technically, we can easily control that range to any by changing the gain of the Modulator with a `GainNode` which is just a tool to scale the amplitude of a signal.

### Envelope

Now, we need to add an **Envelope** for automating that amplitude change you just experiment with.

An envelope in electronic music will generally look like this:

[![](/images/2013/08/500px-ADSR_parameter.svg.png)](http://en.wikipedia.org/wiki/File:ADSR_parameter.svg)

An Envelope corresponds to a **note lifespan**.
It is the minimum required for making our Synth.

We will generally **automate that amplitude through time for each note triggered**.

Here is a demo.
Play, try to hold and release a note (using the Play button or SPACE), and observe how the Spectrum Analyzer is moving:

<iframe width="100%" height="400" src="http://fiddle.jshell.net/tyEKr/32/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/tyEKr/32/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

**Two different envelopes** has been used: one for the **Modulator** and one for the **Carrier** which produce **different sound effects in a note lifespan**.

_We won't make an interactive demo for changing these envelope parameters,
but you can try them in the ZOUND project (or see again the video)._

### Finetuning

Another interesting effect occurs **when the frequency of the Modulator is very close to the frequency of the Carrier**.
In the following example, we have set both oscillators to the same frequency but we expose a "detune" parameter which allows to change a bit the frequency of the Modulator.

<iframe width="100%" height="400" src="http://fiddle.jshell.net/X95S6/10/show/light/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
<a href="http://jsfiddle.net/X95S6/10/" target="_blank" style="display: block; text-align: right">Open on jsfiddle</a>

You can slightly notice that a sound is regulary looping like if it was an LFO effect. You can also visualize it on the graph.

This effect corresponds to the **[phase](http://tinyurl.com/nzkus8) change between both oscillators**: it regulary change from **"in-phase"** state (where it have exactly the same sine waveform at the same time) to a desynchronize **"out-of-phase"** (because of the small detune), and then slightly go to the next "in-phase" step. More the frequencies are close, more it takes time to oscillate from phase to phase.

This effect is especially awesome when you start mixing multiple synths together and finetune a bit each one so they don't sound exactly on the same frequency.

### Modulating the Modulator

There is so much more possibilites to play with,
for instance, the previously introduced Envelope could be mixed
with an LFO to change the Modulator effect in a rythm,
but now let's see how we can...

**...modulate the modulator!**

Eventually we can make a stack of modulators and use different kind of waveforms
for more powerful effects:

![](/images/2013/08/fm_multiple.png)

> Be careful when playing with stack of modulators, it is quite easy to have saturated or noisy sounds.

As an example, I made this experiment which randomly takes different frequencies and amplitude for a stack of 5 modulators:

[**-> http://jsfiddle.net/s2MMR/45/ <-**](http://jsfiddle.net/s2MMR/45/)

Careful! this experiment is a bit crazy! but it shows how different patterns can be when playing with FM.



---

Also, **If you are interested by ZOUND live, [fork it on Github][zoundrepo].**

Frequency Modulation (FM) with Web Audio API


Here is a preview video of the Work In Progress development of [ZOUND live](/2013/07/zound-live/),
the **collaborative modular audio tracker** built with bleeding edge **web technologies**: _Web Audio API, Web MIDI API, WebSocket & Playframework_.

<iframe width="640" height="480" src="//www.youtube.com/embed/621dpTK8OOc" frameborder="0" allowfullscreen></iframe>

<img src="/images/2013/07/nanokontrol.jpg" alt="" class="thumbnail-left" style="width: 150px">

**N.B.** In the video, I've used the nanoKONTROL2 for changing some properties in real time and using the MIDI API.

---

**If you are interested by the project, [fork it on Github](https://github.com/gre/zound-live).**

More to come, stay tuned!


Here is a preview video of the Work In Progress development of ZOUND live, the collaborative modular audio tracker built with bleeding edge web technologies: Web Audio API, Web MIDI API, WebSocket & Playframework.

ZOUND live v1 in development

[0]: /pages/a-world-of-promises/
[1]: http://t.co/OeSukzxv3F
[2]: http://github.com/42loops/Zanimo.js
[3]: http://twitter.com/42loops
[4]: http://github.com/kriskowal/q

# A [World Of Promises][0], episode 4

<img src="/images/2013/07/zanimo_animation_thumbnail.png" alt="" class="thumbnail-left" style="width: 200px" />

_This fourth article on [Q][1] will introduce [Zanimo.js][2],
a Promisified animation library which helps to chain different
CSS transitions with only Promises.
It is very interoperable with any other Promise library,
meaning that you can easily chain Zanimo animations with other asynchronous actions._

[Zanimo.js][2] is a smooth library developed by [@42loops][3] animation library based on the library [Q][4], a Javascript implementation of Promises.

This article is an introduction of the concept of Promises in Javascript with the library Q and will show a real use case of it: Promises used on top CSS Transitions to make powerful and efficient DOM animations in Javascript.



## Zanimo.js

TODO: overview of the library

## Examples

### Recursive tree particle animation

[![tree-particle](/images/2013/05/tree-particle.png)][1]

It turns out that promise is very good tool for animating any recursive things.

TODO

Zanimo.js, a promise-based animation library

Qep4.: Zanimo.js, a promise-based animation library

[zound]: /2012/08/zound-a-playframework-2-audio-streaming-experiment-using-iteratees/
[webmidiapi]: http://webaudio.github.io/web-midi-api/
[webaudioapi]: https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html
[tracker]: http://en.wikipedia.org/wiki/Tracker_(music_software)
[zenexity]: http://zenexity.com

<img src="/images/2013/07/nanokontrol.jpg" alt="" class="thumbnail-left" />

Last week, I initiated, with my [Zenexity][zenexity] Hackday team, **"ZOUND live"**
following the previous ["ZOUND"][zound] experiment but being much more ambitious this time:
using both the **Audio API**, the _new_ **MIDI API** and electronic music software experience,
we start our own **web collaborative audio modular tracker**.

### Live demo of the Hackday application

<iframe width="640" height="480" src="//www.youtube.com/embed/uyHWhCnE4L0" frameborder="0" allowfullscreen></iframe>



## Inspiration

A lot of features have been inspired from existing software like _SunVox_ or _Renoise_.
However, our version uses 100% web technologies and add collaborative and real time aspects.

<img src="/images/2013/07/sunvox.png" style="max-width: 300px" />

### Our Tracker

The application has a [tracker][tracker] where you can put notes.

<img src="/images/2013/07/tracker.png" style="max-width: 300px" />

### Our Audio modules

The application integrates a [modular music](http://en.wikipedia.org/wiki/Modular_software_music_studio) concepts.

<img src="/images/2013/07/nodeeditor.png" />

## The web techs

### About Web MIDI API

We bought a few **cheap MIDI controllers to interact with our application**.

<img src="/images/2013/07/midicontrollers.jpg" class="thumbnail-right" style="max-width: 250px" alt="" />

MIDI means _Musical Instrument Digital Interface_,
it is the **protocol** used by a lot of electronic musical instruments for a few decades.

The [Web MIDI API](webmidiapi) is a recent specification which makes MIDI devices accessible from a web page,
via a Javascript API.

Recently, _Chrome_ has started to [implement it](https://code.google.com/p/chromium/issues/detail?id=163795)
and it is available under _Chrome Canary_ (the dev version) via a _flag_ that you need to enable.

This is the perfect time to start experimenting it!

However, what I feared the most happened on the Hackday: **the MIDI API was broken on the morning
after a Chrome update during the night!** A first version of a browser MIDI permission was implemented
but I never succeeded to make it working. The state of the API seems to be still broken on Mac as of writing.

<blockquote class="twitter-tweet"><p><a href="https://twitter.com/greweb">@greweb</a> If you know how to build chromium, I may be able to provide a patch to enable it. But it isn't so long until Canary supports it.</p>&mdash; とよしま (@toyoshim) <a href="https://twitter.com/toyoshim/statuses/360685543778041857">July 26, 2013</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

Well, that was already too late for the Hackday,
Fortunately we fallbacked on an alternative which relies on a Java applet to access MIDI devices, it was a laggy polyfill though...

**Lesson learned:** a nightly feature is a nightly feature, never assume features you add via flags are stable _(I never did, but it was a Hackday afterall!)_.

BTW, cheers to <a href="https://twitter.com/toyoshim">@toyoshim</a> who is implementing the MIDI API in Chrome :-)

### Using Web Audio API

The [Web Audio API][webaudioapi] is _a high-level JavaScript API for processing and synthesizing audio in web applications_.

The good thing about this API: it is already an **modular audio API**, so it's not so hard to build a modular audio application on top of it!

### Playframework

[Playframework](http://playframework.com/) has been used for **broadcasting events
between clients via WebSocket and synchronize everything on the interface**.
It is only broadcasting and does not save the song yet.

### Backbone.js

[Backbonejs](backbonejs.org) was used for the **models**, **views** and its nice **event system**.
It was a good library for prototyping and architecture the different parts of the application.

I found Backbone.js especially good when linking all parts together and especially for the network logic.
This leads to a very reactive style of programming:

<script src="https://gist.github.com/gre/6107277.js"></script>

## The team

**This project has been started during our monthly Hackday at [Zenexity][zenexity],
I want to thank my 6 awesome coworkers for being part of the project:**

- [@mrspeaker](http://twitter.com/mrspeaker) for his awesome electronic music knowledge.
- [@bobylito](http://twitter.com/bobylito) for his brilliant ideas and his JavaScript skills.
- [@mandubian](http://twitter.com/mandubian) for his playframework experience and JSON superpower!
- [@etaty](http://twitter.com/etaty) for helping with the server synchronization.
- [@skaalf](http://twitter.com/skaalf) for his cool DrumBox module.
- [@Noxdzine](http://twitter.com/Noxdzine) for his talentuous design.

This was actually my first real project managment and it was quite cool!

**Hackday is only one day** and such an ambitious project is hard to achieve one in a row,
the project architecture needed to be a bit ready and having a PoC working before the Hackday. Also I wanted everyone to have fun by experimenting with the Audio API parts and not to be blocked on boring parts.

As a team manager, I also had to define goals to achieve for the Hackday.

Woo, I realize that's **not an easy task to manage a team when running out of time!**

But fortunately, I think we fulfilled it just in time!

We ended the Hackday with a **Real Time demonstration of our application** with 4 people interacting together
with MIDI controllers.

## More to come!

Today, we have a **first working version of a
collaborative tracker with basic modular audio features**:

- MIDI note support + MIDI control assignation allowing to change module properties.
- a unique tracker with a 32 lines loop and 23 tracks.
- Synchronisation of everything: the tracker and modules for all connected clients.
- off-mode allowing one user to prepare a track which is muted for other users.
- play/pause and record mode!
- cursor of users displayed on the tracker.

**Stay tuned because there is so much features to come!**

[**The project on Github**](http://github.com/gre/zound-live)

Last week, I initiated ZOUND live following my previous "ZOUND" experiment but being much more ambitious this time: using both the Audio API, the new MIDI API and electronic music software experience, we start our own web collaborative audio modular tracker.

ZOUND live project initiated

[0]: /pages/a-world-of-promises/
[1]: http://github.com/gre/qanimationframe
[2]: https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/RequestAnimationFrame/Overview.html
[3]: http://creativejs.com/resources/requestanimationframe/
[4]: http://www.paulirish.com/2011/requestanimationframe-for-smart-animating/

# A [World Of Promises][0], episode 3

<img src="/images/2013/07/qanimationframe.jpg" alt="" class="thumbnail-left" style="width: 200px" />

_This third article on [Q][1] is a little parenthesis to the Qep articles series,
featuring the `requestAnimationFrame` Javascript function and its general usage,
and [QanimationFrame][1], its Promisified version used as a "wait for DOM to be ready" API._



## `requestAnimationFrame`

`requestAnimationFrame` is a function which **delays a Javascript function execution to the next browser render frame**.
It takes one argument in parameters which is **the function to call on next repaint**.
_(N.B. there is not anymore a second DOM parameter like a few months ago, see the [spec][2])_

### ...for animation loop

`requestAnimationFrame` helps to easily make a **render loop**:

```javascript
(function loop() {
  requestAnimationFrame(loop);
  render();
})();
```

In that example, the `render` function can contains any Javascript code which updates
some graphics either using Canvas or DOM.

A good practice is to always **compute time-relative** animations and
never assume the framerate to be constant.

```javascript
function badRenderFunction() {
  someObject.x += 0.1; // 10 pixels per 100 frame.
  // not so good with non-constant framerate
}
```

```javascript
var lastTime = Date.now();
function goodRenderFunction() {
  var now = Date.now();
  var delta = now - lastTime; // in milliseconds
  lastTime = now;
  someObject.x += 0.01 * delta; // 10 pixels per second
  // good because function of time
}
```

More information on `requestAnimationFrame` can be found [here][3] or [here][4].

### ...for waiting a DOM update

**We will now focus on another interesting benefit of that function:**

Instead of using `requestAnimationFrame` for a render loop,
**you can use it only once** in order to **wait for the next DOM update**.

There is a lot of use-cases where you need to wait for the next DOM update
and `requestAnimationFrame` is perfect for that.

Most of the code you can see on the internet rely on using a `setTimeout` with an arbitrary time
given in second parameters _(sometimes 30, sometimes 0 !?)_.
This is, in my humble opinion, a wrong approach because you will never know if the repaint has
really been performed.

## QanimationFrame

`QanimationFrame` is a function which takes a **DOM Element** in parameter and return a
**Promise of that "ready" DOM element**.

**`QanimationFrame (elt: DOM Element) => Promise[DOM Element]`**

**N.B.:** Even if `requestAnimationFrame` doesn't have anymore a second _DOM element_ parameter,
I found it quite cool that you can give it as argument and retrieve it back to manipulate it.
It also makes the function more composable because it behaves like an identity Promise function.
We will also see benefits when using with other DOM Promise libraries.

### Basic example

```javascript
var elt = document.createElement("div");
elt.innerHTML = "Hello world";
// wait for the DOM to be ready before using the height
QanimationFrame(elt).then(function (elt) {
  console.log("height=" + elt.offsetHeight);
});
```

### Composability

```javascript
function createDivInBody(html) {
  var elt = document.createElement("div");
  elt.innerHTML = html;
  document.body.appendChild(elt);
  return elt;
}

var height = Q.fcall(createDivInBody, "Hello world!<br/>How are you today?")
  .then(QanimationFrame)
  .then(function (elt) {
    return elt.offsetHeight;
  });

height.then(function (height) {
  console.log("height is " + height);
});
```

There is of-course a lot of more examples and use-cases of that library.

## Next episode

Next episode is a big one!

We will introduce you a Promisified animation library called **Zanimo.js** which
helps to chain different **CSS transitions with only Promises**.
It is very interoperable with any other Promise library,
meaning that you can easily chain Zanimo animations with other asynchronous actions.

This third article on Q is a little parenthesis to the Qep articles series, featuring the requestAnimationFrame Javascript function and its general usage, and QanimationFrame, its Promisified version used as a "wait for DOM to be ready" API.

Qep3.: QanimationFrame

[0]: /pages/a-world-of-promises/
[1]: http://github.com/kriskowal/q
[2]: http://github.com/gre/qimage
[3]: http://wiki.commonjs.org/wiki/Promises/A
[4]: http://dom.spec.whatwg.org/#promises
[5]: http://wiki.commonjs.org/wiki/Promises/B
[6]: http://wiki.commonjs.org/wiki/Promises/D
[7]: https://npmjs.org/package/qimage

# A [World Of Promises][0], episode 2

<img src="/images/2013/07/qimage_then_thumbnail.jpg" alt="" class="thumbnail-right" style="width: 200px" />

_This second article on [Q][1] will introduce you how to easily
turn a callback API into a promise API using Deferred objects.
It will also present the new W3C specification of Promise and finish
with the implementation of [Qimage][2], a simple Image Promise wrapper._



## Deferred objects

[Q][1] splits the concept of Promise in two parts: one part is the **Deferred object**, another is the **Promise object**.

A **Deferred object** is an object which just aims to control the state of a Promise.
It allows to do one of the two following actions (one time only):

- `.resolve(value)`: moving from _pending_ to **_fulfilled_ with a value**.
- `.reject(error)`: moving from _pending_ to **_rejected_ with an error**.

<img src="/images/2013/07/promise.png" style="max-width: 300px; width: 100%" />

A **Promise object** can be obtained from a Deferred object via the `promise` field.
In [Q][1], a Promise is **read-only**: you can basically only do `.then` with it
and there is no such `resolve` or `reject` method on a Promise.

> a Deferred is "resolvable", a Promise is "thenable".

**_N.B._**: _this separation also exists in other languages but with different names (for instance in Scala: Promise / Future)._

### `Q.defer()`

The method Q.defer() will return a new **Deferred object** initialized in a _pending_ state.

```javascript
var d = Q.defer();
setTimeout(function () {
  d.resolve(42);
}, 500);
var promise = d.promise;
// ...
promise.then(function (value) {
  console.log("the universe = " + value);
});
```

Note that the [Promises/A][3] spec only specifies the concept of **Promise**.
It does not defines the "Deferred" part.
Up to the Promise library to implement its own way of resolving / rejecting the value of a Promise.

There is also [Promises/B][5] and [Promises/D][6] to define that though.

### About the DOM.Promise specification

a [new DOM specification draft][4] has born recently and is a bit different from the Q style,
the "Deferred" object (called a **Resolver**) is given as an argument of the function given at Promise instanciation.

```javascript
var promise = new /*DOM.*/ Promise(function (resolver) {
  setTimeout(function () {
    resolver.resolve(42);
  }, 500);
});
promise.then(function (value) {
  console.log("the universe = " + value);
});
```

## Qimage: Wrapping the Image API

We will now show you how to easily **wrap the DOM Image API into a Promise API with Q**.
Before showing the implementation, let's explore the possibilities of such API.

**`Qimage (url: String) => Promise[DOM Image]`**

Here is how we want our `Qimage` API to look like:

```javascript
var promise = Qimage("http://imagesource.com/image.png");
promise.then(
  function (image) {
    // image instanceof Image
  },
  function (error) {
    // error instanceof Error
  }
);
```

We can use it like this:

```javascript
Qimage("images/foo.png").then(
  function (img) {
    document.body.appendChild(img);
  },
  function (error) {
    document.body.innerHTML = "Unable to load the image";
  }
);
```

Now we define `Qimage` as a Promise library, **we can then use all the power of Promises,
combine Promises together, chain different Promise APIs**...

```javascript
Q.all([Qimage("res1.png"), Qimage("res2.png"), Qimage("res3.png")]).spread(
  function (res1, res2, res3) {
    document.body.appendChild(res1);
    document.body.appendChild(res2);
    document.body.appendChild(res3);
  }
);
```

This wrapper makes a simple but powerful Image Loading library module.

### Implementation

Here is how `Qimage` works:

```javascript
var Qimage = function (url) {
  var d = Q.defer();
  var img = new Image();
  img.onload = function () {
    d.resolve(img);
  };
  img.onabort = function (e) {
    d.reject(e);
  };
  img.onerror = function (err) {
    d.reject(err);
  };
  img.src = url;
  return d.promise;
};
```

...and that's it!

Note that **the Deferred object is isolated** in the `Qimage` function scope.

Only the (read-only) Promise is accessible from the outside when returned by the function.

**How simple is wrapping a callback API into a Promise API!**

---

[Qimage][2] is released as a micro-lib and available on [Github][2] and [NPM][7].

## Next episode

Next episode will feature **`requestAnimationFrame`**,
_a fundamental function generally used for performing efficient Javascript animations_.
We will show you **QanimationFrame** and how we can use it as a **Promisified "wait for DOM to be ready" API**.

This second article on Q will introduce you how to easily turn a callback API into a promise API using Deferred objects. It will also present the new W3C specification of Promise and finish with the implementation of Qimage, a simple Image Promise wrapper.

Qep2.: Deferred objects, Qimage

[0]: /pages/a-world-of-promises/
[1]: http://github.com/kriskowal/q
[2]: http://github.com/gre/qimage
[3]: https://github.com/kriskowal
[4]: http://wiki.commonjs.org/
[5]: http://domenic.me/2012/10/14/youre-missing-the-point-of-promises/
[6]: https://raw.github.com/kriskowal/q/master/design/README.js
[7]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/EventLoop
[8]: http://jquery.com/
[9]: http://wiki.commonjs.org/wiki/Promises/A
[10]: http://tritarget.org/blog/2012/11/28/the-pyramid-of-doom-a-javascript-style-trap/

# [A World Of Promises][0], episode 1

_This article is the first of a series of small articles
on the Q Javascript library and its eco-system.
This article is a brief introduction to Q Promises._

<img src="/images/2013/07/promise_then_thumbnail.jpg" alt="" class="thumbnail-left" />

[Q][1] is a **Promise library** in **Javascript**
created 4 years ago by [Kris Kowal][3] who is one of the main contributor to [CommonJS][4]
where we can find the **[Promises/A][9]** specification.

[Q][1] is probably **the most mature and powerful Promise library in Javascript**
which inspired a lot of libraries like [jQuery][8].
It exposes a complete API with, in my humble opinion,
good ideas like the separation of concerns between a "Deferred" object (the resolver)
and a "Thenable" Promise (the read-only promise).

This article is a brief introduction to Q Promises with some examples.
For more information on the subject, I highly recommend reading
the article ["You're Missing the Point of Promises"][5]
and [the Q implementation design README][6].



## What is a Promise

A **Promise** is an object representing a **possible future value** which has
a `then` method to access this value via callback. A Promise is initially
in a _pending_ state and is then either _fulfilled_ with a value or _rejected_ with an error.

![Schema representing Promise states: pending -> fulfilled|rejected](/images/2013/07/promise.png)

### Some properties

It is **immutable** because the Promise value never changes and each `then` creates a new Promise.
As a consequence, one same Promise can be shared between different code.

It is **chainable** through the `then` method (and other Q shortcut methods),
which transforms a Promise into a new Promise without knowing what's inside.

It is **composable** because the `then` method will unify any Promise returned as
a result of the callback with the current Promise (act like a map or flatmap).
[Q][1] also has a `Q.all` helper for combining an Array of Promise into one big Promise.

## A solution against the [Pyramid of Doom][10] effect

_Javascript_ is by nature an **asynchronous language** based on an [event loop][7] which enqueue events.
As a consequence, there is no way to block long actions (like Image Loading, ajax requests, other events), but everything is instead asynchronous:
Most of Javascript APIs are using **callbacks** - functions called when the event has succeeded.

**Problem with callbacks** is when you start having a lot of asynchronous actions.
It quickly becomes a [Callback Hell](http://callbackhell.com/).

### Example

Here is a simple illustration, let's say we have 2 functions,
one for **retrieving some photos meta-infos from Flickr** with a search criteria: `getFlickrJson(search, callback)`,
another for **loading an image from one photo meta-info**: `loadImage(json, callback)`.
Of-course both functions are asynchonous so they need a callback to be called with a result.

With this callback approach, we can then write:

```javascript
// search photos for "Paris", load and display the first one
getFlickrJson("Paris", function (imagesMeta) {
  loadImage(imagesMeta[0], function (image) {
    displayImage(image);
  });
});
```

_(Imagine what it can look like with more nested steps.)_

> we can easily turn a _callback_ API into a _Promise_ API

#### Promise style

`getFlickrJson` and `loadImage` can now be rewritten as Promise APIs:

Each function has clean signatures:

- `getFlickrJson` is a `(search: String) => Promise[Array of ImageMeta]`.
- `loadImage` is a `(imageMeta: ImageMeta) => Promise[DOM Image]`.
- `displayImage` is a `(image: DOM Image) => undefined`.

...and are easily pluggable together:

```javascript
getFlickrJson("Paris")
  .then(function (imagesMeta) {
    return imagesMeta[0];
  })
  .then(loadImage)
  .then(displayImage, displayError);
```

**This is much more flatten, concise, maintainable and beautiful!**

Note that if we want to be safer we can write:

```javascript
Q.fcall(getFlickrJson, "Paris")
  .then(function (imagesMeta) {
    return imagesMeta[0];
  })
  .then(loadImage)
  .then(displayImage, displayError);
```

`Q.fcall` will call the function with the given parameters and ensure wrapping the returned value into a **Promise**.
So my code should continue working even if we change signatures to:

- `getFlickrJson` is a `(search: String) => Array of ImageMeta`.
- `loadImage` is a `(imageMeta: ImageMeta) => DOM Image`.

One other cool thing about this chain of Promises is **we can easily add more steps** between two `then` step, for instance a DOM animation, a little delay, etc.

### Error Handling

But a much important benefit is, unlike the callbacks approach,
we can properly **handle the error in one row** because one of the following steps eventually fails:

- `getFlickrJson` fails to perform the ajax request to retrieve the Flickr JSON data.
- The array returned by Flickr was empty so `loadImage` throws an exception.
- The `loadImage` fails (e.g. the image is unavailable).

This is called **propagation** and is exactly how **exceptions** work.

**Promise Error Handling** really looks like **Exception Handling**.

If it would be possible to have two methods:

- `getFlickrJsonSync` is a `(search: String) => Array of ImageMeta`.
- `loadImageSync` is a `(imageMeta: ImageMeta) => DOM Image`.

Then, the blocking code would look like this:

```javascript
try {
  var imagesMeta = getFlickrJsonSync("Paris");
  var firstImageMeta = imagesMeta[0];
  var image = loadImageSync(firstImageMeta);
  displayImage(image);
} catch (e) {
  displayError(e);
}
```

_...which is very close to Promise style._

**Q Promises also unify Exceptions and Rejected Promises**:
throwing an exception in any Q callback will result in a rejected Promise.

```javascript
var safePromise = Q.fcall(function () {
  // following eventually throws an exception
  return JSON.parse(someUnsafeJsonString);
});
// safePromise is either fulfilled with a JSON Object
// or rejected with an error.
```

> Error handling with the callbacks approach is hell:

```javascript
getFlickrJson(
  "Paris",
  function (imagesMeta) {
    if (imagesMeta.length == 0) {
      displayError();
    } else {
      loadImage(
        imagesMeta[0],
        function (image) {
          displayImage(image);
        },
        displayError
      );
    }
  },
  displayError
);
```

## Next episode

Next episode, we will show you how to create your own Promises with _Deferred_ objects.
We will introduce **Qimage**, a simple Image loader wrapped with Q.

---

Special Kudos to <a href="http://twitter.com/42loops">@42loops</a> & <a href="http://twitter.com/bobylito">@bobylito</a>
for bringing Q in my developer life :-P

This article is the first of a series of small articles on the Q Javascript library and its eco-system. It is a brief introduction to Q Promises.

Qep1.: Q, a Promise library

Playframework simple deployment scripts

[2]: http://gre.github.io/glsl.js/examples/balls
[3]: http://gre.github.io/glsl.js/examples
[4]: http://gre.github.io/glsl.js/docs
[5]: http://github.com/gre/glsl.js
[6]: http://gre.github.io/glsl.js/test
[7]: http://gre.github.io/glsl.js/examples/pong/
[8]: http://glsl.heroku.com
[13]: http://gre.github.io/glsl.js/examples/helloworld
[15]: http://www.khronos.org/registry/gles/specs/2.0/GLSL_ES_Specification_1.0.17.pdf
[16]: http://glsl.heroku.com/
[24]: http://gre.github.io/glsl.js/examples/canvas-text/
[25]: http://gre.github.io/glsl.js/examples/video/
[26]: http://gre.github.io/glsl.js/examples/mario_sprites/

[![glsl_mario](/images/2013/02/glsl_mario.jpg)][2]

**TL;DR. WebGL is super powerful and efficient. This library abuses this power for efficient 2D.**

glsl.js is a subset of a WebGL library which focuses on making the GLSL (OpenGL Shading Language) easy and accessible for vizualisation and game purposes (2D or 3D).

- **[Bouncing balls example video tutorial][2]**
- [Open other examples][3]
- [API Documentation][4]
- [Fork me on Github][5]
- [Unit tests][6]

[![glsl_pong](/images/2013/02/glsl_pong.jpg)][7]

## Why?

**WebGL is a very low level and stateful API**. Actually the WebGL API **is** the OpenGL API.

I wanted to make a graphic library where you wouldn’t have to know about this API but still have access to the powerful OpenGL Shading Language called GLSL.

Do you know [glsl.heroku.com][8]? It’s a cool platform for demoscene where you can experiment some nice effects in GLSL. My library extends this concept of rendering in one whole fragment shader (which takes the plain canvas) but also provides a way to inject your own Javascript variables.

### DRY

**WebGL is not DRY at all**, you always have to repeat yourself both on the GLSL and on the Javascript part (especially for synchronizing variables).  
Worse than that, you have to know in your Javascript code what are the GLSL types of every variable to synchronize.

How boring is that:

```javascript
// Synchronizing the new values of 2 variables in pure WebGL.

var myInt = 1;
var myIntLocation = gl.getUniformLocation(program, "myInt");
myInt;
gl.uniform1i(myFloatLocation, myInt); // 1i means one integer

var myVector2 = { x: 1.3, y: 2.4 };
var myVector2Location = gl.getUniformLocation(program, "myVector2");
gl.uniform2f(myVector2Location, myVector2.x, myVector2.y); // 2f means float[2]
```

**glsl.js** provides a DRY and simple way to synchronize Javascript variables.

First, the library will handle for you the UniformLocations.

More important, and unlike the WebGL API and many WebGL libraries, **you will never have to define the type of your variables from the Javascript with glsl.js!** You just define it once in your shader!

How it works behind is the framework will statically parse your GLSL and infer types to use for the synchronization. The right `gl.uniform*` function is called by Javascript reflection.

It now simply becomes:

```javascript
// Set the values of 2 variables in glsl.js
this.set("myInt", 1);
this.set("myVector2", { x: 1.3, y: 2.4 });
// ... see also this.sync() and this.syncAll()
```



More technically, **glsl.js** is a subset\* of a WebGL library which focus on **making the GLSL (OpenGL Shading Language) easy and accessible** for vizualisation and game purposes (2D or 3D).

> \* Subset, because we only focus on using a _fragment shader_ (the _vertex shader_ is static and take the full canvas size), But don’t worry, you have a long way to go with just one _fragment shader_.

The concept is to split the **rendering part in a GLSL fragment** from the **logic part in Javascript** of your app/game. Both part are linked by **a set of variables** (the state of your app/game).

![schema](https://f.cloud.github.com/assets/211411/133026/5ed79ff8-709b-11e2-85dd-60332f74dc31.png)

**glsl.js** aims to abstract every GL functions so you don’t have to learn any OpenGL API.  
What you only need to care about is the logic in Javascript and the rendering in GLSL.

By design, **you can’t mix logic and render part**, this approach really helps to focus on essential things separately.

### Efficiency

Basically, this design is efficient because the Javascript logic will take some CPU while the rendering will take the graphic card.

Today, WebGL is widely supported on modern desktop browsers. It’s not yet the case on mobile and tablet.

However, using Chrome Beta, I’m able to run my HTML5 game at 60fps on my Nexus 4, which is quite promising for the future.

<iframe width="640" height="360" src="http://www.youtube.com/embed/EzTCdjpdTfk?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

_Enough talking, let’s see some examples now…_

### [][11]Hello World Example

[11]: #hello-world-example

Here is an Hello World example. For more examples, see [/examples][3].

```html
<canvas id="viewport" width="600" height="400"></canvas>
<script id="fragment" type="x-shader/x-fragment">
  #ifdef GL_ES
  precision mediump float;
  #endif
  uniform float time;
  uniform vec2 resolution;
  void main (void) {
    vec2 p = ( gl_FragCoord.xy / resolution.xy );
    gl_FragColor = vec4(p.x, p.y, (1.+cos(time))/2., 1.0);
  }
</script>
<script src="../../glsl.js" type="text/javascript"></script>
<script type="text/javascript">
  var glsl = Glsl({
    canvas: document.getElementById("viewport"),
    fragment: document.getElementById("fragment").textContent,
    variables: {
      time: 0, // The time in ms
    },
    update: function (time, delta) {
      this.set("time", time);
    },
  }).start();
</script>
```

[![screenshot](https://f.cloud.github.com/assets/211411/132729/e702c2b4-7090-11e2-8904-49e904e6c5a2.png)][13]

### [][14]GLSL: OpenGL Shading Language

[14]: #glsl-opengl-shading-language

> GLSL is a high-level shading language based on the syntax of the C programming language. (Wikipedia)

GLSL gives a very different way of thinking the rendering: basically, in a main function, you have to **set the color (`gl_FragColor`) of a pixel for a given position (`gl_FragCoord`)**.

As a nice side effect, GLSL is vectorial by design: it can be stretch to any dimension.

GLSL is efficient because it is compiled to the graphic card.

GLSL provides an interesting collection of **types** (e.g. `int`, `float`, `vec2`, `vec3`, `mat3`, `sampler2D`,… and also arrays of these types) and **functions** (e.g. `cos`, `smoothstep`, …).

[Here is a good reference for this][15].

You can also deeply explore the awesome collection of [glsl.heroku.com][16]. Any of glsl.heroku.com examples are compatible with **glsl.js** if you add some required variables (\*time\*, _mouse_, …).

### [][17]App/Game Logic

[17]: #appgame-logic

You must give to Glsl a `canvas` (DOM element of a canvas), a `fragment` (the GLSL fragment code), the `variables` set, and the `update` function.

Then you can start/stop the rendering via method (`.start()` and `.stop()`).

The `update` function is called as soon as possible by the library. It is called in a `requestAnimationFrame` context.

You must define all variables shared by both logic and render part in a Javascript object `{varname: value}`.  
Variables must match your GLSL uniform variables. Every time you update your variables and you want to synchronize them with the GLSL you have to manually call the `sync` function by giving all variables name to synchronize.

**Exemple:**

```javascript
Glsl({
  canvas: canvas,
  fragment: fragCode,
  variables: {
    time: , // The time in seconds
    random1:
  },
  update: function (time, delta) {
    this.set("time", time);
    this.set("random1", Math.random());
  }
}).start();
```

**Note:** _under the hood, a type environment of uniform variables is inferred by parsing your GLSL code._

### [][18]Using arrays

[18]: #using-arrays

Hopefully, GLSL also supports arrays. You can actually bind a Javascript array to a GLSL uniform variable.

**Example:**

In GLSL,

```glsl
uniform float tenfloats[10];
```

In Javascript,

```javascript
var glsl = Glsl({
  ...
  variable: {
    tenfloats: new Float32Array(10)
  },
  update: function () {
    this.tenfloats[3] = Math.random();
    this.sync("tenfloats");
  }
}).start();
```

Alternatively, you can still use a classical javascript Array (but native Javascript arrays are prefered because more efficient).

Use `Int32Array` for `int[]` and `bool[]`.

Vector arrays are also possible. In Javascript, you will have to give a linearized array.  
For instance,  
a `vec2[2]` will be `[vec2(1.0, 2.0), vec2(3.0, 4.0)]` if `Float32Array(1.0, 2.0, 3.0, 4.0)` is used.

### [][19]Using objects

[19]: #using-objects

Even more interesting now, you can synchronize a whole object into the GLSL world. This is very interesting for Object-Oriented approach.

**Example:**

In GLSL,

```glsl
struct Circle {
  vec2 center;
  float radius;
}
uniform Circle c1;
bool inCircle (vec2 p, Circle c) {
  vec2 ratio = resolution/resolution.x;
  return distance(p*ratio, c.center*ratio) < c.radius;
}
void main (void) {
  vec2 p = ( gl_FragCoord.xy / resolution.xy );
  if (inCircle(p, c1))
    gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
  else
    gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0);
}
```

In Javascript,

```javascript
function Circle (x, y, radius) {
  this.center = { x: x, y: y };
  this.radius = radius;
  this.originalRadius = radius; // not visible by GLSL
}
Circle.prototype.update = function () {
  this.radius = this.originalRadius Math.sin(Date.now()/100);
}
var c1 = new Circle(0.5, 0.5, 0.1);
Glsl({
  ...
  variable: {
    c1: c1
  },
  update: function (time, delta) {
    c1.update();
    this.sync("c1");
  }
}).start();
```

structs inside structs are also supported:

```glsl
struct Circle {
  vec2 center;
  float radius;
}
struct Player {
  Circle circle;
  bool visible;
}
```

### [][20]Using Arrays of Objects

[20]: #using-arrays-of-objects

The two previous chapters can be assemble!

Yes man, Array of JS object is possible!

```glsl
uniform Circle circles[2];
// circles[0].radius
// …
```

```javascript
Glsl({
  ...
  variable: {
    circles: [ new Circle(0.1, 0.1, 0.2), new Circle(0.2, 0.3, 0.2) ]
  },
  ...
}).start();
```

### [][21]Using images

[21]: #using-images

GLSL:

```glsl
uniform sampler2D img;
```

Javascript:

```javascript
var image = new Image();
img.src = "foo.png";
var glsl = Glsl({
  ...
  variable: {
    img: image
  }
});
img.onload = function () {
  glsl.start();
}
```

Note: Using an image loader library can be a good idea.

In GLSL, you will need to use the texture lookup functions to access the image color for a given coordinate. E.g. `texture2D(img, coord)`. (see the [specs][15]).

#### See also

[The mario_sprites example][26]

### [][22]Using another canvas

[22]: #using-another-canvas

[![hello_world_text_glsl_js](/images/2013/02/hello_world_text_glsl_js.png)][24]

### Using

[![glsl_js_video](/images/2013/02/glsl_js_video.png)][25]

## See also

<iframe width="480" height="360" src="http://www.youtube.com/embed/kxBkfy_8JEs" frameborder="0" allowfullscreen=""></iframe>

WebGL is super powerful and efficient. This library abuses this power for efficient 2D.

glsl.js, a Javascript + GLSL library = DRY & efficient

[1]: http://scala-lang.org
[2]: http://www.playframework.org/documentation/2.0/Iteratees
[3]: http://gre.github.io/playCLI-examples/api
[4]: http://github.com/gre/playCLI
[5]: http://github.com/gre/playCLI-examples
[6]: /2012/08/zound-a-playframework-2-audio-streaming-experiment-using-iteratees/
[7]: http://mandubian.com/2012/08/27/understanding-play2-iteratees-for-normal-humans/

[8]: http://gre.github.io/playCLI-examples/api/#enumerate(command:scala.sys.process.ProcessBuilder,chunkSize:Int,terminateTimeout:Long)(implicitec:scala.concurrent.ExecutionContext):play.api.libs.iteratee.Enumerator[Array[Byte]]
[9]: http://www.playframework.org/documentation/api/2.1-RC1/scala/index.html#play.api.libs.iteratee.Enumerator
[10]: http://gre.github.io/playCLI-examples/api/#pipe(command:scala.sys.process.ProcessBuilder,chunkSize:Int,terminateTimeout:Long)(implicitec:scala.concurrent.ExecutionContext):play.api.libs.iteratee.Enumeratee[Array[Byte],Array[Byte]]
[11]: http://www.playframework.org/documentation/api/2.1-RC1/scala/index.html#play.api.libs.iteratee.Enumeratee

[12]: http://gre.github.io/playCLI-examples/api/#consume(command:scala.sys.process.ProcessBuilder,terminateTimeout:Long)(implicitec:scala.concurrent.ExecutionContext):play.api.libs.iteratee.Iteratee[Array[Byte],Int]
[13]: http://www.playframework.org/documentation/api/2.1-RC1/scala/index.html#play.api.libs.iteratee.Iteratee
[14]: http://www.scala-lang.org/api/current/index.html#scala.sys.process.package
[15]: http://www.playframework.org/documentation/api/2.1-RC1/scala/index.html#play.api.libs.iteratee.Done$
[16]: #pipe(command:scala.sys.process.ProcessBuilder,chunkSize:Int,terminateTimeout:Long)(implicitec:scala.concurrent.ExecutionContext):play.api.libs.iteratee.Enumeratee[Array[Byte],Array[Byte]]
[17]: http://www.playframework.org/documentation/api/2.1-RC1/scala/index.html#play.api.libs.iteratee.Input$$EOF$

> **TL;DR.** PlayCLI is a new [Scala][1] library to work with UNIX commands and [Play-Iteratees][2] (a scala implementation of Iteratees facilitating the handling of data streams reactively). Here’s an overview:

<iframe src="http://gre.github.io/playCLI-examples/embedder.html#index.html" frameborder="0" width="550" height="452"></iframe>

## Links

- [The scala API][3].
- [PlayCLI source code (Github)][4].
- [PlayCLI Examples application (Github)][5].

### SBT

```scala
"fr.greweb" %% "playcli" % "0.1"
```



## Why PlayCLI

After having made [Zound][6] in a HackDay (an experiment to generate an audio stream with playframework iteratees and through the WAVE format), I figured out this was going to be hard to make it work with multiple audio format: _tell me if I’m wrong but_, there are not so much audio libraries in Java/Scala, or most of them does not support stream handling (and not reactively), and it was going to be crazy to re-implement everything in Scala (both in term of cost and performance).

Besides, **UNIX has plenty of tools** to do this and:

1.  they are **complete** and provide a lot of options
2.  they are **easy to use** (see how Bash is powerful as a consequence)
3.  Most of them **support streams** out of the box (via stdin / stdout)
4.  They are very **efficient** (written in C / assembly)

So why not re-use them from our reactive code?

### Similarities with UNIX pipes

> Take the expressivity of UNIX pipes, bring the power of Scala, mix it with Play Framework and you got a powerful framework for handling real-time and web streaming.

Play Iteratees are an elegant & powerful way to handle streams reactively, and I’ve actually always understood them like UNIX pipes, you have the same reactive code style: linearized declarative way of handling streams.

**Bash:**

```bash
cat words.txt | grep $word > result.txt
```

**Scala:**

```scala
Enumerator.fromFile("words.txt") &>
  splitByNl &> // split a stream of Array[Byte] into stream of String (not impl here)
  Enumeratee.filter(_.containsSlice(word))  |>>>
  fileWriter // consume the steam while storing in a file (not impl here)
```

or if you prefer the “without symbol” version:

```scala
Enumerator.fromFile("words.txt").
  through splitByNl.
  through Enumeratee.filter(_.containsSlice(word)).
  run fileWriter
```

However, It’s biased to say Iteratees are only UNIX pipes, they are more than that, but I’m not going to extend on that subject, they are at least statically typed and safe (it’s more than just a stream of bytes, see [this article][7]).

So if Iteratees are at least UNIX pipes, why can’t we use Unix pipes from iteratees?

**PlayCLI provides a bridge to use scala.sys.Process with play-iteratees.**

## More about PlayCLI

_(this is a copy of the API documentation)_

### Overview

Depending on your needs, you can **Enumerate / Pipe / Consume** an UNIX command:

[CLI.enumerate][8] is a way to create a stream from a command which **generates output**  
(it creates an [Enumerator][9][Array[Byte]] )

[CLI.pipe][10] is a way to pipe a command which **consumes input and generates output**  
(it creates an [Enumeratee][11][Array[Byte],Array[Byte]])

[CLI.consume][12] creates a process which **consumes a stream** – useful for side effect commands  
(it creates an [Iteratee][13][Array[Byte],Int])

#### Examples

```scala
import playcli._
import scala.sys.process._

// Some CLI use cases
val tail = CLI.enumerate("tail -f /var/log/nginx/access.log")
val grep = (word: String) => CLI.pipe(Seq("grep", word))
val ffmpeg = CLI.pipe("ffmpeg -i pipe:0 ... pipe:1") // video processing
val convert = CLI.pipe("convert - -colors 64 png:-") // color quantization

// Some usage examples
val sharedTail = Concurrent.broadcast(tail)
Ok.stream(sharedTail).withHeaders(CONTENT_TYPE -> "text/plain") // Play framework

val searchResult: Enumerator[String] = dictionaryEnumerator &> grep("able") &> aStringChunker

Ok.stream(Enumerator.fromFile("image.jpg") &> convert).withHeaders(CONTENT_TYPE -> "image/png")

Enumerator.fromFile("video.avi") &> ffmpeg &> ...
```

### Process

CLI uses [scala.sys.process][14]  
and create a Process instance for each UNIX command.

A CLI process is terminates when:

- The command has end.
- stdin and stdout is terminated.
- [Done][15] is reached (for [enumerate][8] and [pipe][16]).
- [EOF][17] is sent (for [pipe][10] and [consume][12]).

CLI still waits for the Process to terminate by asking the exit code (via `Process.exitCode()`).  
If the process is never ending during this phase, it will be killed when `terminateTimeout` is reached.

PS: Thanks to implicits, you can simply give a String or a Seq to the CLI.\* functions a `ProcessBuilder`.

### Mutability

[enumerate][8] and [pipe][10] are **immutable**, in other words, re-usable  
(each result can be stored in a val and applied multiple times).  
**A new process is created for each re-use**.

[consume][12] is **mutable**, it should not be used multiple times: it targets side effect command.

### Logs

A “CLI” logger (logback) is used to log different information in different log levels:

- **ERROR** would mean a CLI error (not used yet).
- **INFO** used for the process’ stdout output of a [CLI.consume][12].
- **DEBUG** used for the process life cycle (process creation, process termination, exit code).
- **WARN** used for the process’ stderr output.
- **TRACE** used for low level information (IO read/write).

## Conclusion

I’m eager to see what you guys can do with such an API, it enables a lot of possibility, I’m especially thinking about multimedia purposes (using powerful commands like: ImageMagick, ffmpeg, sox,…).

PlayCLI is a new Scala library to work with UNIX commands and Play-Iteratees (a scala implementation of Iteratees facilitating the handling of data streams reactively)

PlayCLI: Play Iteratees + UNIX pipe

[3]: http://wtfjs.com/
[4]: https://en.wikipedia.org/wiki/Floating_point
[6]: http://news.ycombinator.com/item?id=5051525
[7]: http://silentmatt.com/biginteger/

<blockquote class="twitter-tweet" lang="fr"><p>@<a href="https://twitter.com/greweb">greweb</a> : Let's do a kickstarter to build the 1st space rocket running on embedded Javascript... I think we can discover new physics rules!</p>&mdash; mandubian (@mandubian) <a href="https://twitter.com/mandubian/status/289422662101504000">10 janvier 2013</a></blockquote>

It is [common][3] in Javascript to have unexpected behaviors, but this one is particulary vicious.

> 10000000000000000 === 10000000000000001

**Javascript doesn’t have integer type but lets you think it has.** `parseInt` and `parseFloat` built-in functions, the fact that “1″ is displayed as “1″ and not as “1.0″ (like many languages) contribute to the general misunderstood.

**In Javascript, all numbers are floating numbers and are prone to [floating point approximation][4].**

When you write `var i = 1;`, and you console.log it, Javascript is nice, you obtain `1` and not `1.0000000000000001`.

But you can experiment that, in Javascript, `1.0000000000000001 === 1` is true…

> I hear you, telling me that _this sounds OK, floating point approximation rules, right?_

But the same thing occurs for big numbers:

```javascript
10000000000000000 === 10000000000000001;
```

Oh **F\*\*K** !

[edit] where in python:  
![](https://pbs.twimg.com/media/BAg2wRyCIAAGuXW.png:large)

## Termination of loops

The following is worse:

<script src="https://gist.github.com/4504986.js"></script>

is logging `10000000000000000` forever!

Because 10000000000000001 can’t exist in Javascript with approximations, 10000000000000001 is 10000000000000000, so you can’t increment this value, and you are stuck in this crazy f\*\*king loop.

Conclusion, _Program termination proof_ sounds hard to reach in Javascript!



## How many numbers in a 1000 range?

Between 10000000000000000 and 10000000000001000, there are actually 750 Javascript integers.

<script src="https://gist.github.com/4505510.js"></script>

## Real World Example

The issue can actually **lead to real web application disaster**. Imagine if your database use Long for id (well like almost every databases in the world, like twitter does), and **if you use the id as number in Javascript and not as string**, you can have strange behaviors like never being able to represent and access a resource from the Javascript or worse!

<script src="https://gist.github.com/4505517.js"></script>

## TL;DR. The lesson

This is not something new, floating point approximation, but the way Javascript fix values to round the approximations mislead us.

Now, simple thing, **Avoid numbers when approximation is not permitted** like for resource id (especially when you retrieve it from a server).

This probably impacts your JSON APIs because it’s the last thing you had think of!

Otherwise, **if you need to manipulate big integers in Javascript use a library for that**.

Example: [http://silentmatt.com/biginteger/][7]

[EDIT]  
9007199254740993 (which is 2^53 1) is the smallest not representable integer in Javascript. In other words, you can trust Javascript numbers before this integer!

[EDIT 2]  
[Thanks to 0×0 on HackerNews][6] who told me the twitter id issue example really happened in a previous twitter API:

Javascript doesn’t have integer type but lets you think it has. In Javascript, all numbers are floating numbers and are prone to floating point approximation.

Be careful with JS numbers!

[1]: https://github.com/playframework/Play20/commit/0f1ec1479e490f2c8af4cd79dd0b6a14b0ea9f75
[2]: http://www.playframework.org/
[3]: http://mandubian.com/2012/08/27/understanding-play2-iteratees-for-normal-humans/

A few weeks ago, [we’ve introduced][1] a new feature in [Play Framework][2]: the `Enumerator.outputStream` method, allowing you to work with Java API requiring an `OutputStream` to generate content, for instance the `java.util.zip` API.

**Now, let’s see how easy it is to serve a big Zip generated on-the-fly without memory load with Play Framework.**



## The Zip generation example

<script src="https://gist.github.com/4058734.js?file=Application.scala"></script>

This demo shows how to **generate a zip file on-the-fly** and directly **stream it** to an HTTP client **without loading it in memory or storing it in a file**.

It uses an `Enumerator` created with the `Enumerator.outputStream` method.  
The `OutputStream` provided by the method is then plugged to the Java’s `ZipOutputStream`.

For the example, we have generated a zip containing 100 text files, and each text files contains 100’000 random long numbers (yes, 100’000 !).

The zip size is approximatively 100 Mb. (and is generated in about 3Mb/s in my machine in localhost, but this can be improved)

The huge benefit of this is the download starts instantly, it means the Zip is streamed while it is generated.

## Show me the code!

Internally, it is implemented with a `Concurrent.unicast`, and a simple implementation of an `OutputStream` pushing into the unicast’s channel:

<script src="https://gist.github.com/4058734.js?file=Enumerator.scala"></script>

## About Iteratee and Enumerator

If you want to learn more about Iteratee concepts in Play Framework, I recommend you [this article][3].

A few weeks ago, we’ve introduced a new feature in Play Framework: the Enumerator.outputStream method, allowing you to work with Java API requiring an OutputStream to generate content, for instance the java.util.zip API.

Play Framework – Enumerator.outputStream

![ZOUND](/images/2012/07/ZOUND.png)

Last Friday was HackDay #7 at [Zenexity][2], and we decided to work on a real-time audio [experiment][3] made with [Play Framework][4]. The plan was to use an audio generator ([JSyn][5], an audio synthesizer), encode the output and stream it all using Play Iteratees to pipe everything in real-time.

[2]: http://zenexity.com
[3]: http://github.com/gre/zound
[4]: http://playframework.org
[5]: http://www.softsynth.com/jsyn/
[7]: https://twitter.com/mrspeaker
[12]: http://www.playframework.org/
[13]: scala-lang.org/
[14]: http://sadache.tumblr.com/post/26784721867/is-socket-push-bytes-all-what-you-need-to-program
[15]: http://www.infoq.com/presentations/Play-I-ll-See-Your-Async-and-Raise-You-Reactive
[16]: https://github.com/playframework/Play20/tree/master/framework/src/play/src/main/scala/play/api/libs/iteratee
[17]: http://en.wikipedia.org/wiki/WAV
[19]: http://en.wikipedia.org/wiki/Broadcasting_(networking)

<iframe width="640" height="360" src="http://www.youtube.com/embed/taDLKTcNHnQ?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

**First of all, let’s highlight some interesting part of the project, then get into some of the details.**

Thanks to [@Sadache][6] for his Iteratee expertise, we ended up with a simple line of code that does all of the hard work:

[6]: https://twitter.com/Sadache

```scala
val chunkedAudioStream = rawStream &> chunker &> audioEncoder
```

You can think of the `&>` operator as the UNIX pipe `|`. So we simply take the `rawStream`, chunk it with a `chunker` and encode it with an `audioEncoder`.

Now, **rawStream** is the raw stream of audio samples (numbers between -1 and 1) generated by the audio synthesizer. Next, the **chunker** buffers a data stream into chunk of bytes. For instance, if you send data stream at 1Kb/s to a 10Kb chunker, it will output one chunk of size 10Kb every 10 seconds. And finally, the **audioEncoder** takes **audio samples** and outputs encoded bytes implementing an audio format (like WAVE).

We can then make a broadcast of the stream:

```scala
val (sharedChunkedAudioStream, _) =
  Concurrent.broadcast(chunkedAudioStream)
```

And then the **sharedChunkedAudioStream** is now a shared stream for every consumer (clients). All that’s left to do is to stream it over HTTP:

```scala
def stream = Action {
  Ok.stream(audioHeader >>> sharedChunkedAudioStream).
     withHeaders( ("Content-Type", audio.contentType) )
}
```

The `>>>` operator means “concatenation”, so here we’re concatenating the **audio header** (given by the format like WAVE) with the current **chunked audio stream**. We also send the right HTTP **Content-Type** header (like “audio/wav” for WAVE).

Another interesting part of the project is the **multi-user web user interface: allowing users to interact with the sound synthesis**.

Using [@mrspeaker][7]‘s audio synthesis expertise, we started creating a synthesizer generator – 3 oscillators, various wave shapes, frequency and volumes, and finally flowing through a high pass filter before entering our “rawStream” above.

Thanks to the Play framework goodness, **this audio stream can be both consumed by the web page with an HTML audio tag, and with a stream player such as VLC!** Ok, that’s the project – let’s have a closer look at some of the concepts…



## What is sound?

> Sound is a mechanical wave that is an oscillation of pressure transmitted through a solid, liquid, or gas, composed of frequencies within the range of hearing and of a level sufficiently strong to be heard, or the sensation stimulated in organs of hearing by such vibrations. **_Wikipedia_**

We can represents the sound like any wave as a graphic of the amplitude (the oscillation pressure) as a function of time. Here you see it in Audacity:

![sound-audacity](/images/2012/07/sound-audacity.png)

Electricity is used to pump these amplitudes to your speakers, over time.

### About primitive wave sounds

There are some patterns – some primitives waves – we can easily generate with computers (or before with analog oscillators). Those are well known by mathematicians and physicians: Sine wave, Triangle wave, Square wave,…

[![](/images/2012/07/557px-Waveforms.svg_.png)][10]

[10]: http://en.wikipedia.org/wiki/File:Waveforms.svg

A sine wave produce a smooth tone, whereas Triangle and Square wave are more aggressive sounds. The shorter a wave period is, the lower the note you hear: it’s called the frequency.

### How is sound represented by computer?

Whereas analog oscillators generate sounds in an \*almost** continuous stream of electricity, computers are not able to generate continuous stream of data. This is why with computers the sound is divided in to discrete **samples**, usually **44100 samples per second\*\* for standard CD quality audio. Each sample is a value (amplitude) for a given time position.

[See Sampling (wikipedia)][10].

[10]: http://en.wikipedia.org/wiki/Sampling_(signal_processing)

If you zoom in Audacity, you can actually see each sample:  
![audacity-zoom](/images/2012/07/audacity-zoom-ah.png)
This is an “AH” timbre of my voice. A timbre is unique to everyone, it’s the pattern the sound wave take when you speak. **The amplitude of an audio sample is usually represented as a Real number between -1.0 and 1.0**.

\*_ electricity is not strictly continuous, we have electrons out there!_

Ok, Let’s go back to our experiment now!

## The experiment

Our experiment is using [Play Framework][12] and is written in [Scala language][13]. Specifically, our project takes advantage of Play framework’s powerful **Iteratee**s.

> Take the expressivity of UNIX pipes, bring the power of Scala, mix it with Play Framework and you got a powerful framework for handling real-time and web streaming.

The iteratee (and related constructs) can take a bit of getting used to. I recommend checking out [this article on Iteratees in Play][14] and/or [this presentation][15] if you are interested in learning more about Play2 and reactive programming with Iteratees. And if you just want to see how it work – you can read the source code at [Play20 Github source code][16].

### Generating the audio stream

```scala
val (rawStream, channel) = Concurrent.broadcast[Array[Double]]
val zound = new ZoundGenerator(channel).start()
```

We create an `Array[Double]` broadcast which return two values: the **rawStream** will be used to read the generated data, and the **channel** used by the generator to push generated audio samples. We give this channel to the **ZoundGenerator**. The `.start()` then starts the audio generation. All of the generation is done using the JSyn library.

Here’s a snippet from the **ZoundGenerator** class showing the connection between **JSyn** and **Channel**:

```scala
class ZoundGenerator(output: Channel[Array[Double]]) {
  val out = new MonoStreamWriter()

  val synth = {
    val synth = JSyn.createSynthesizer()
    synth.add(out)
    out.setOutputStream(new AudioOutputStream(){
      def close() {}
      def write(value: Double) {
        output.push(Array(value))
      }
      def write(buffer: Array[Double]) {
        write(buffer, , buffer.length)
      }
      def write(buffer: Array[Double], start: Int, count: Int) {
        output.push(buffer.slice(start, start count))
      }
    })
    synth
  }
  // ...
```

We have to implement the methods of AudioOutputStream – but it’s just a matter of pushing each audio sample to the channel. It’s that simple!

### Encoding the raw audio stream

For now, we have only implemented the [WAVE format][17]. Basically, WAVE has 2 parts; the WAVE header which describes important information (like the framerate and the bits per sample), and the data.  
The data is encoded in a simple manner I won’t describe here but you can look to the encoder I made here:

Now more interesting, let’s wrap it with Play Iteratees:

```scala
val audio = MonoWaveEncoder() // instanciate the WAV encoder
val audioHeader = Enumerator(audio.header)
val audioEncoder = Enumeratee.map[Array[Double]](audio.encodeData)
```

**_N. B._**: _Remember that Scala is a typed language but where the type declaration is optional because the compiler can infer the type._

**audioHeader** is an `Enumerator` which means it can _produce_ data, and here the data is the audio header. More precisely it’s an `Enumerator[Array[Byte]]` because audio.header is an `Array[Byte]`. Note that contained data is not “consumed” like it would be for an `InputStream`. Each time you use this enumerator, it gives you its entire content.

**audioEncoder** is an `Enumeratee[Array[Double], Array[Byte]]`. It takes an `Array[Double]` from input and returns an `Array[Byte]` as output. The input is a raw array of audio samples (double numbers between -1.0 and 1.0). The output is the encoded array of bytes.

More formally, an `Enumeratee[A, B]` is an _adapter_ which maps some data of type A to new data of type B. You can implement the way the data is transformed with the map function. Here we just give it the `audio.encodeData` function.

### Streaming it

We can basically stream the audio stream with Play2 like so:

```scala
def stream = Action {
  val audioStream = rawStream &> audioEncoder
  Ok.stream(audioHeader >>> audioStream).
     withHeaders( (CONTENT_TYPE, audio.contentType) )
}
```

The `rawStream &> audioEncoder` takes the raw stream and **pipes** it into the encoder which results in the encoded audio stream. `audioHeader >>> audioStream` will **concatenate** `audioHeader` with `audioStream`. Hence, the first thing the server will do is start sending the audio header to the client **and then** stream the audio in real-time.

**A client can connect at any time and will hear current stream**, so it should simultaneously hear the same thing as any other client (with some delay depending on the client buffer). If the generator stops emitting audio samples, the http client will stop receiving audio data – but it will still be waiting for the server, so the audio play will pause until the server re-sends new audio samples. **That is pretty cool!** – because of the way iteratees work, the stream doesn’t just die when all of the input is consumed.

#### A chunker to reduce HTTP packet numbers

Up to now we’ve been streaming the audio in **very small chunks** because by default JSyn writes out arrays of just 8 audio samples and the `.stream()` function consumes all data as it comes. This means _a lot_ of HTTP chunks per second are sent – which is less efficient and take more bandwidth.

In order to fix this, we need to use a **buffer on the server side**. In other words, instead of sending audio samples as they come we need to **group audio samples**. We have currently grouped audio samples in arrays of 5000 which is quite reasonable (it’s about 10 chunks per second using 44100 samples/s). We can easily change this later. This logic is implemented in an `Enumeratee` we called “chunker”. In that sense, it is reusable and modular:

```scala
val chunker = Enumeratee.grouped(
  Traversable.take[Array[Double]](5000) &>> Iteratee.consume()
)
```

And now, we can easily plug it in like this:

```scala
def stream = Action {
  val chunkedAudioStream = rawStream &> chunker &> audioEncoder
  Ok.stream(audioHeader >>> chunkedAudioStream).
     withHeaders( (CONTENT_TYPE, audio.contentType) )
}
```

### Broadcast

Now, another improvement we made was to **factorize this chunking and encoding part: avoiding having this computing tasks done for every stream consumer**.

Basically, we move it out of the stream function:

```scala
val chunkedAudioStream = rawStream &> chunker &> audioEncoder
def stream = Action {
  Ok.stream(audioHeader >>> chunkedAudioStream).
     withHeaders( (CONTENT_TYPE, audio.contentType) )
}
```

But to allow broadcasting, we have to use a broadcast:

```scala
val chunkedAudioStream = rawStream &> chunker &> audioEncoder
val (sharedChunkedAudioStream, _) =  =
  Concurrent.broadcast(chunkedAudioStream)
def stream = Action {
  Ok.stream(audioHeader >>> sharedChunkedAudioStream).
     withHeaders( (CONTENT_TYPE, audio.contentType) )
}
```

Here we only care about the enumerator (the left argument in the Tuple2), we put the wildcard "\_" to ignore the return value.

[![](/images/2012/07/320px-Broadcast.svg_.png)][19]

Using a broadcast, generated audio samples pushed by the audio generator can be simultaneously spread to multiple consumers. This is perfect for our needs, multiple players can connect to this web radio!

### Avoiding the server load

The last important fix we made was to **avoid the server load**:

```scala
  def stream = Action {
    Ok.stream(audioHeader >>> sharedChunkedAudioStream
      &> Concurrent.dropInputIfNotReady(50)).
       withHeaders( (CONTENT_TYPE, audio.contentType) )
  }
```

If a client is opening the stream connection but doesn’t consume enough or doesn’t consume it at all (download is paused), the server will fill in memory the chunks to send to the client and the server can reach an _out of memory_ exception. To avoid that **we have to drops chunks if the consumer is not ready**. Then the client will just lose messages if it is not ready (in our case, we give them 50 milliseconds).

And this is what `Concurrent.dropInputIfNotReady(50)` is actually doing – with yet another **Enumeratee**! **Dropping old chunks is really what we want in an audio streaming application**: We want the consumer to subscribe to the current audio stream and not to continue from where they stopped.

### Client consumers

#### HTML5 Audio tag

In HTML5, we have the Audio tag – and we can just consume our stream like this:

```html
<audio src="/stream.wav"></audio>
```

Or if we want to make it auto loading:

```html
<audio src="/stream.wav" preload autoplay controls></audio>
```

It may be a bit “wrong” to use `` for streaming, but it works because we are using it as if the server was hosting a static audio file. The only disputable hack is to have to set the max ChunkSize in the WAVE header which is 2147483647 (it’s about 6 hours 45mn!), so the browser believes the audio is not finished.

The issue we are currently facing is this crazy latency (a few seconds) between user actions and the produced sound. This problem is due to the browser audio cache buffer: if we were able to minimize it we would have an almost real-time audio player.

#### Playing it with VLC

This stream is spread through HTTP so we need a HTTP client to consume it. But a HTTP client doesn’t mean only browsers! We can also use VLC for this, as if it was a web radio! One advantage of using VLC is it suffers far less latency (presumably because the cache buffer is smaller than the audio tag).

![vlc](/images/2012/07/vlc.png)

## Making the real-time control UI

Our experiment **mixes different oscillators to generator one sound**. The web user interface allows a user to control the parameters of those. Two knobs control the **volume** and the **pitch** (tuned to a dorian mode scale) and you can select the oscillator **wave primitive** (sine, sawtooth, square, noise). It’s not fancy at the moment – but JSYN offers a lot of features for expanding our simple demo.

![](/images/2012/07/Capture-d’écran-2012-07-31-à-16.42.15.png)

This interface is **multi-users**, so if you use it with other people, **the interface will stay synchronized over multiple browsers** (turn the knobs, change the wave primitive, …). All this is done with WebSockets, and on the server-side it’s using, again, **Iteratees**!

The workflow is simple: When someone does some action on the user interface, events are sent to the server. These events are interpreted by the _ZoundGenerator_ resulting in updates to the audio synthesis configuration. These events are then broadcast to each client, and some Javascript handlers are called in order to keep the interface synchronized.

## Source code

**[Fork me on Github][3]**

## What’s next?

This was just a simple demo to show the power and flexibility of Play2′s Iteratee concept. Because of the modular nature, extending the demo is easy. For example, we could plug a new audio encoder such an OGG encoder. The code would be simple and we could even choose on a request-by-request basis which encoder to use:

```scala
import Concurrent.broadcast
val (chunkedWaveStream, _) =
  broadcast(rawStream &> chunker &> waveEncoder)
val (chunkedOggStream, _) =
  broadcast(rawStream &> chunker &> oggEncoder)

def stream(format: String) = Action {
  val stream = format match {
    case "wav" => waveHeader >>> chunkedWaveStream
    case "ogg" => oggHeader >>> chunkedOffStream
  }
  Ok.stream(stream).
     withHeaders( (CONTENT_TYPE, audio.contentType) )
}
```

**Now it’s up to you!**

Hopefully you get a feel for the possibilities of stream processing and piping with Play. You can now reuse these concepts and make your own stuff: Maybe you don’t need to generate sounds on the fly, but instead you simply want to play a collection of audio files and stream them like radio? **Well you can make a web radio engine now!**.

But that’s just the beginning – I would love to see someone taking the concept, and running even further… Do you know that in Youtube, during the time you are uploading a video, Youtube is already re-encoding it and can start streaming it _before_ the file has finished uploading? Hmm, that’s starting to sound almost simple…

Zound uses an audio generator (JSyn, an audio synthesizer), encode the output and stream it all using Play Iteratees to pipe everything in real-time.

Zound, a PlayFramework 2 audio streaming experiment using Iteratees

[1]: http://youcanmakevideogames.com/
[2]: http://7dfps.org/
[3]: http://www.ludumdare.com/
[4]: http://gre.github.io/dta
[8]: http://caniuse.com/#search=webgl
[12]: http://www.egonelbre.com/js/jsfx/
[16]: http://www.opengl.org/documentation/glsl/
[17]: http://glsl.heroku.com/
[19]: https://github.com/gre/dta/blob/master/app/models/models.scala
[20]: http://playframework.org/

![](/images/2012/07/dta1.png)

Last week was the [7dfps challenge][2], an open challenge where participants had to make a FPS in only one week.
Such contest are very very interesting for those who want to experiment with things. Challenging yourself is IMO the best way to learn new things. You may also know the famous [“Ludum Dare” contest][3].

I learned to use Backbone.js and Three.js (a famous library on top of WebGL) in only one week, so you have no excuse to not be able to do the same!

[-> You can make games!][1]

> “If Lawnmower Man f\*\*\*\*d Tron on the bonnet of a tank”  
> **_YouBigNugget_**

I’ve only used web technologies, no need of any plugin, just a recent browser like Chrome / Firefox.

This is the result:

<iframe width="640" height="360" src="http://www.youtube.com/embed/g9CldBI9C6E?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

and you can play it here:

**[Play the game][4]**



## Overview of a one week game development

### Backbone.js, for the model, events and class inherence

I’m a fan of the “do it yourself” idea, not using any library or only using small 140byt.es codes. But the frequent issue with that is (1) always doing the same thing again and again, (2) taking a lot of time on the architecture, and not finishing anything. When you have a due date, relying on libraries and frameworks could save you a lot of time.  
I’ve choose Backbone.js for its Model architecture with class inherence, a get/set system, and also its event system bound to model instances, the destroy function with the “destroy” event to bind on,… It was also a new library to learn for me.

#### Models

Here is the class diagram of the game:

![not available](/images/2012/07/f5dea341.jpg)

### Learning Three.js, a 3D library on top of WebGL.

WebGL is [more and more supported by browsers][8].  
WebGL means OpenGL in the web. It allows to make efficient and hardware accelerated 3D computation.

Here is the same, not using any library but using pure WebGL wasn’t possible in one week! This is why I’ve chosen to use Three.js, probably today the most popular WebGL library.  
I was impressed how Three.js is finally not so hard to use, knowing some basic 3D concepts from my old Blender days.

You create a `Scene`, add a `Camera`, add Meshes to the scene, A `Mesh` has a `Material` and a `Geometry`, … everything very straighforward.

One challenging part was when trying to compute global world position relative to a given object position, for instance to compute the Bullet initial position and orientation from the Tank position and orientation.

Fortunately I’ve got some help ![:)][4] and got the answer: multiply your vector with the worldMatrix of the mesh.

<blockquote class="twitter-tweet" data-in-reply-to="212609230891524096" width="550" lang="fr"><p>@<a href="https://twitter.com/greweb">greweb</a> Should be calculatable quite easily. Multiply the position vector by the object’s matrixWorld property.</p>
<p>&mdash; Paul Lewis (@aerotwist) <a href="https://twitter.com/aerotwist/status/212617930024816641" data-datetime="2012-06-12T18:50:39+00:00">Juin 12, 2012</a></p></blockquote>

<blockquote class="twitter-tweet" data-in-reply-to="212609230891524096" width="550" lang="fr"><p>@<a href="https://twitter.com/greweb">greweb</a> var position = new THREE.Vector3().getPositionFromMatrix( object.matrixWorld );</p>
<p>&mdash; Mr.doob (@mrdoob) <a href="https://twitter.com/mrdoob/status/212648943673290752" data-datetime="2012-06-12T20:53:53+00:00">Juin 12, 2012</a></p></blockquote>

### Playing with AI

Like TankKeyboardControls, I’ve created a new “TankControls” for computer tanks: **TankRandomControls** was the first dumb one, it just does random things:

```javascript
function TankRandomControls () {
var self = this;
self.moveForward = false;
self.moveBackward = false;
self.moveLeft = false;
self.moveRight = false;
self.fire = false;
self.fireMissile = false;
var i = ;
setInterval (function () { // take random decisions every 0.5 second
  i;
self.moveForward = i%3== && Math.random() > 0.2;
self.moveBackward = !self.moveForward && Math.random() > 0.5;
self.moveLeft = Math.random() < 0.1;
self.moveRight = Math.random() < 0.1;
self.fire = Math.random() > 0.2;
self.fireMissile = Math.random() < 0.2;
}, 500);
}
```

**TankRemoteControls** was the second one using some simple AI rules:

- Try to avoid walls and objects
- Either do random things or target a tank (more likely)
- Target the closest tank, update target every 5 seconds
- Turn the tank to the target tank, shoot bullets and missiles
- Move forward if the target is far away / Move backward if the target is too close

See the source code here: .

### Sounds

I’ve used [JSFX][12], an experimental library, were you can generate sounds based on a few parameters.  
It’s a 8-bit sound generator perfect for generate old-school sounds.

So you can create each sound in Javascript like this:

```javascript
SOUNDS = {
  bullet: jsfxlib.createWave([
    "noise",
    7.0,
    0.18,
    0.0,
    0.082,
    0.0,
    0.222,
    20.0,
    800,
    2400.0,
    -0.428,
    0.0,
    0.0,
    0.01,
    0.0003,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.992,
    0.0,
    0.0,
    0.22,
    0.0,
  ]),
  missile: jsfxlib.createWave([
    "noise",
    0.0,
    0.12,
    0.0,
    0.546,
    0.0,
    0.856,
    64.0,
    250,
    1063.0,
    0.28,
    0.086,
    0.024,
    5.4329,
    0.3565,
    0.466,
    -0.638,
    0.058,
    0.008,
    0.0,
    0.0,
    -0.114,
    0.216,
    0.98,
    -0.984,
    1.0,
    0.307,
    0.988,
  ]),
  explosion: jsfxlib.createWave([
    "noise",
    1.0,
    0.4,
    0.02,
    0.682,
    1.746,
    1.97,
    100.0,
    378.0,
    2242.0,
    -0.55,
    -0.372,
    0.024,
    0.4899,
    -0.1622,
    0.262,
    0.34,
    0.724,
    0.0205,
    -0.102,
    0.0416,
    -0.098,
    0.1,
    0.805,
    0.094,
    0.428,
    0.0,
    -0.262,
  ]),
  collideWall: jsfxlib.createWave([
    "noise",
    0.0,
    0.4,
    0.0,
    0.056,
    0.0,
    0.296,
    20.0,
    560.0,
    2400.0,
    -0.482,
    0.0,
    0.0,
    0.01,
    0.0003,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.0,
    1.0,
    0.0,
    0.0,
    0.0,
    0.0,
  ]),
};
// ...
// SOUNDS.bullet.play()
```

The jsfxlib.createWave function returns a HTML5 Audio element and you can play with its API (.play(), .pause(), …).  
But doing this way, you will not be able to play a sound at the same time so I’ve made a buffer system which duplicate N times the sound in different audio elements.  
I have also try to generate different sounds to randomize it a little.

See the full source code here: .

### Post Processing Effects with GLSL shaders

I was very impressed by the power of GLSL for its possibilities and efficiency.  
GLSL are definitely the indispensable thing you need to add a better atmosphere in your games.

#### Before

![](/images/2012/06/before.png)

#### After

![](/images/2012/06/after_.png)

and when getting shot:

![](/images/2012/06/after.png)

These effects are done by combining these two GLSL effects.  
Here is the GLSL code of these effects.

#### The radio noise effect

<script src="https://gist.github.com/2950478.js?file=radionoise.frag"></script>

#### The shot interference

<script src="https://gist.github.com/2950478.js?file=perturbation.frag"></script>

### Wait! what is this crazy “GLSL” language?

GLSL is an OpenGL language close to the C syntax design to have a direct control of the graphic pipeline. You can directly add passes to the rendering process with GLSL shaders.  
GLSL gives you a lot of very useful types (like vectors, matrix, …) and functions (like smoothstep, …). [Read the spec][16] to know more about it.  
I also recommend you to experiment the [GLSL Sandbox][17]. You can see awesome demos and their codes shared by people made with GLSL. It also have an online IDE to easily code and instantly test your shaders.

### WebGL and Three.js integration

You can use GLSL in different ways with Three.js. You can add a GLSL shader to an object material, and you can also add GLSL shaders on top of the Canvas (post-processing). We will only see how to add GLSL shaders as a post processing render on the entire Canvas.

Fortunately Three.js have some utils classes to make the GLSL shaders integration easier.

I have been inspired from the awesome work done here: .

There is a lot of code out there, so I’ve try to extract the minimum required for mixing the 2 GLSL shaders for a post-processing on the entire canvas of a Three.js scene:

<iframe style="width: 100%; height: 400px;" src="http://jsfiddle.net/jggvJ/7/embedded/" frameborder="0" width="320" height="240"></iframe>

As you can see, you can easily inject your own Javascript variables in a GLSL shader to make a bridge between the JS and the GLSL code and so having quite generic and configurable shaders.  
Quite cool!

### Adding game UI

Web, with HTML and CSS, allows to have different containers, layers, positioning systems,…  
Perfect! For the game UI, we used different elements:

![](/images/2012/06/ui.png)

Radar and Damage are implemented with an independent Canvas while Level is a simple text div.

For instance, this is Damage (I called LifeIndicator):

```javascript
(function(){

var LifeIndicator = function (nodeId) {
this.canvas = document.getElementById(nodeId);
this.ctx = this.canvas.getContext("2d");
this.life = 1;
this.render();
}

LifeIndicator.prototype.setLife = function (life) {
this.life = life;
this.render();
}

LifeIndicator.prototype.render = function () {
var c = this.ctx;
var w = c.canvas.width, h = c.canvas.height;
c.clearRect(, , w, h);
// TODO
var g = Math.floor(255*this.life);
var r = 255-g;
c.fillStyle = "rgb(" r "," g ",0)";
var wt = 6;
var ht = 12;
c.fillRect((w-wt)/2, , wt, ht);
c.fillRect(, ht, w, h);
}

window.LifeIndicator = LifeIndicator;

}());
```

## Play Framework integration

I was planning to make a multiplayer game but I couldn’t find the time for this.  
I use Play Framework 2 and its power and concepts for handling streams (even if I don’t use it yet).  
The only part I can show you for now is the game map generation. For making a multiplayer game, I needed to have the game state on server side to be able to submit game infos (map, players, …) to new players.

This is a few scala code to generate a nice distribution of random objects in the map:

```scala
object Game {
  def createRandom: Game = {
    val random = new Random()
    val half = 5000
    val size = 2*half
    val split = 4
    val objects =
    Range(, split).map { xi =>
      Range(, split).map { yi =>
        val s = size.toDouble / split.toDouble
        val x = -half.toDouble math.round(s*(xi random.nextDouble));
        val y = -half.toDouble math.round(s*(yi random.nextDouble));
        var sizeRandom = random.nextDouble
        val w = 200.*math.ceil((1-sizeRandom)*8.);
        val h = 200.*math.ceil(sizeRandom*8.);
        RectObj(Vec3(x,y,), w, h)
      }.toList
    }.toList.flatten
    Game( (Vec3(-half, -half, ), Vec3(half, half, )), List(), objects, List() )
  }
}

case class Game (bounds: Tuple2[Vec3, Vec3], chars: List[Char], objects: List[GameObj], dynamics: List[GameDyn])
...
```

[See the full source][19] (some code may not be used).

## Still an unfinished game

There is more things to do now:

- More visual effects
- More sound effects
- A better collision system (using a physic engine?)
- Multiplayer
- A better gameplay with some goals, different kind of games, …

### Initial multiplayer objective rescheduled

My initial game release was focus on the game core, graphisms and gameplay.

I was unfortunately not ready enough to make the multi-player real-time part for the first week sprint but I have some though on the subject.  
I was asking myself what are the best way to make the game synchronisation between clients while trying to keep as much client-side code as possible. I wanted a scalable decentralized game. I had some though on how to solve this issue. For instance, when a client shoots, he sends a “shoot” event with the timestamp, server just streams events (with a tick frequency) sent by clients and clients replay the game exactly the same way everywhere (using all these time-based events) with some interpolation with the current time.  
I need to think more about this now, and try to use [PlayFramework][20].

## Source code

[http://github.com/gre/dta](http://github.com/gre/dta)

**[EDIT] You may be mainly interested by the [main.js][21]. It shows how powerful the even-driven programming is, for plugging components together.  
**

[21]: https://github.com/gre/dta/blob/master/app/assets/javascripts/main.js

## Special thanks

[@mrspeaker][22] for helping me with Three.js & also collision system,  
[@mrdoob][23] & [@aerotwist][24] for replying to my newbies questions,  
guys on IRC (#three.js),  
and of-course 7dfps guys.

[22]: http://twitter.com/mrspeaker
[23]: http://twitter.com/mrdoob
[24]: http://twitter.com/aerotwist

I learned to use Backbone.js and Three.js (a famous library on top of WebGL) to make a FPS in only one week.

How I learned Backbone.js, Three.js, GLSL in one week

I’ve always been fascinated by the power of **using existing web applications as external tools**: you don’t need to install anything on your computer but you can **rely on the web**.

We can **externalize the intelligence of applications in servers** and **easily make updates**, while having any terminal consuming them with a **minimal OS environment**.  
_Cloud_ or whatever you call it, it’s awesome.

WOA is our common architecture for making applications. Clients of web servers can be anything you want, not only desktop browsers, but also mobiles, tablets, other web services, and… **command-line**!

And today, as an example, we will use [Google Closure Compiler web service][1] to **minimize a Javascript file with only cURL**.

[1]: https://developers.google.com/closure/compiler/docs/api-ref



**cURL** is a CLI swiss army knife of transferring data and it is perfect for testing, debugging and consuming web services.

**Google Closure Compiler** check and “compile” your Javascript file. By compile, it means optimizing its size by renaming variables and removing spaces and comments. Javascript compilation has because an essential phase of major javascript libraries.

## Bash script examples

### Download and minimize the last version of Illuminated.js

```bash
URL=https://raw.github.com/gre/illuminated.js/master/src/illuminated.js
OUTPUT=illuminated.min.js
curl -d compilation_level=SIMPLE_OPTIMIZATIONS -d output_format=text -d output_info=compiled_code -d code_url=$URL http://closure-compiler.appspot.com/compile > $OUTPUT
```

### Minimize a local JS file

```bash
LOCAL_FILE=./mysuperlib.js
OUTPUT=mysuperlib.min.js
curl -d compilation_level=SIMPLE_OPTIMIZATIONS -d output_format=text -d output_info=compiled_code --data-urlencode "js_code@${LOCAL_FILE}" http://closure-compiler.appspot.com/compile > $OUTPUT
```

use Google Closure Compiler web service to minimize a Javascript file with only cURL.

Minimize your Javascript files with cURL

[1]: http://bit.ly/LZ2dq1
[2]: http://gre.github.io/illuminated.js
[3]: http://github.com/gre/illuminated.js
[4]: /2012/05/illuminated-js-2d-lights-and-shadows-rendering-engine-for-html5-applications/#gettingstarted
[5]: /2012/05/illuminated-js-2d-lights-and-shadows-rendering-engine-for-html5-applications/#underthehood
[6]: http://en.wikipedia.org/wiki/Canvas_element
[7]: http://gre.github.io/illuminated.js/gettingstarted.html
[8]: http://en.wikipedia.org/wiki/Ray_tracing_(graphics)
[9]: /images/2012/05/step11.jpg
[10]: /images/2012/05/step21.jpg
[11]: /images/2012/05/step31.jpg
[12]: /images/2012/05/step4.jpg
[13]: http://blog.marmakoide.org/?p=1
[14]: /images/2012/05/sampling.jpg
[15]: http://en.wikipedia.org/wiki/Tangent_lines_to_circles

[![](/images/2012/05/illuminatedjs.jpg)][1]

[Click on the image to open it!][1]

## Wow! what’s this?

It’s a **2D scene** containing 2 **lights** and 13 different **objects** rendered in **real-time** by a **Javascript library** I made called **Illuminated.js**.

The library is designed to add some **awesome effects to your existing applications**. Adding **a cool atmosphere for your applications and games** can make the difference!

**[Try the editor][2]** and **[Get the source code][3]**.

In this article, we will introduce the basic usages of _Illuminated.js_ and APIs, and then explain how the engine works step-by-step.

- [API – Getting started][4]
- [Technical notes – how does it work?][5]



## How can I use it?

The library uses [HTML5 Canvas][6] to draw lights and shadows – so you can simply drop it straight into your existing Canvas applications: you just need to add some code in your render function and maintaining a binding between your application logic and the _Illuminated.js_ objects.  
Not using canvas? No worries! In theory, if you have an existing application or game made in full DOM, you could use _Illuminated.js_ behind this, playing with z-index.

## <a id="gettingstarted"></a> Getting started

### Basic concepts

All the classes of the package live in `window.illuminated`.

A **Light** describes a light emit source.  
An **OpaqueObject** specifies an 2D object used by a Lighting.  
A **Lighting** defines the lighting of a light through a set of opaque objects, each object stops the light and casts shadows.  
A **DarkMask** defines a dark layer which hides dark area not lighted by a set of lights. It should be drown on the top-layer to hide objects which are far from the light. This effect produces a better atmosphere and is perfect for game where light are essential (where hiding invisible area is part of the difficulty).

### Example of a basic scene rendering

[  
Click here to open this example.  
![](/images/2012/05/gettingstarted.jpg)
][7]

## Lights and Objects

### Vec2

```javascript
new Vec2(x, y);
```

Vec2 represents a 2d position or a 2d vector. It is used everywhere in _Illuminated.js_.

Vec2 is inspired from Box2d’s Vec2 except that in _Illuminated.js_ a Vec2 vector is immutable. It means every methods create a new Vec2 instance and you can safely use a same Vec2 instance everywhere because the immutability guarantees the non-modification of properties.

### Lights

For now, we have only implemented one kind of light: a **Lamp** which is basically a radial gradient. A Lamp can also be “oriented”, it means lighting more far in a given direction.

#### Lamp

```javascript
new Lamp();

new Lamp({ position: new Vec2(12, 34) });
```

every parameters:

```javascript
new Lamp({
  position: new Vec2(12, 34),
  distance: 100,
  diffuse: 0.8,
  color: 'rgba(250,220,150,0.8)',
  radius: ,
  samples: 1,
  angle: ,
  roughness:
})
```

It defines a **Lamp** placed at a **position**, with a maximum emiting **distance**, a **diffuse** parameters to define the light penetration in objects.  
The **radius** defines the size of the light. Bigger the size is, Higher shadows are smoothed. The **samples** is an important parameters to define the quality of this smooth.  
The **angle** and **roughness** parameters are used for oriented lamp: angle defines the orientation while roughness defines the roughness of the effect.

### Light methods

You can easily create your own Light type by implementing its methods.

#### .mask(ctx)

Render a mask representing the visibility (used by DarkMask).

#### .render(ctx)

Render the light (without any shadows).

#### .bounds()

Return the Rectangle bound of the light representing where the light emission limit. `{ topleft: vec2, bottomright: vec2 }`

#### .forEachSample(fn)

Apply a function fn for each light sample position. By default it’s called once with the light position.

### Opaque Objects

In _Illuminated.js_, an object which cast shadows is called an opaque object. That’s why every types inherits OpaqueObject.

DiscObject and PolygonObject are the two available primitive objects.

#### DiscObject

A “DiscObject” is basically a 2D circlar object. You must define its center **position** and its **radius**:

```javascript
new DiscObject({ position: new Vec2(80, 50), radius: 20 });
```

#### PolygonObject

PolygonObject also has some derivated classes you can use: **RectangleObject**, **LineObject**.

You can instanciate these different objects like this:

```javascript
new PolygonObject([ new Vec2(, ), new Vec2(10, 10), ... ]) // an array of points
new RectangleObject(topleft, bottomright) // topleft and bottomright positions of the rectangle
new LineObject(a, b) // an object defined by the line from a to b.
```

### OpaqueObject methods

You can easily create your own object type by implementing OpaqueObject methods.

#### .bounds()

Return the Rectangle bound of the object. `{ topleft: vec2, bottomright: vec2 }`

#### .contains(point)

Return `true` if the object contains a **point**.

#### .path(ctx)

Build the path of the object shape in a 2d context **ctx**.

#### .cast(ctx, origin, bounds)

Fill every shadows with **ctx** projected by the **origin** point in the object and in a given **bounds**.

## Lighting and DarkMask

Previous defined classes was representing datas we will now use to perform lightings and masks.

### Lighting

A Lighting defines the lighting of one light through a set of opaque objects.

```javascript
new Lighting({ light: light, objects: [ object1, object2, ... ] })
```

#### .compute(width, height)

will compute shadows casting.

#### .cast(ctx)

will draw black shadows on the **ctx** canvas 2d context.  
You usually don’t have to use it if you use `render()`.

#### .render(ctx)

will draw the light with its shadows on **ctx** canvas 2d context.

### DarkMask

A DarkMask defines a dark layer which hides dark area not lighted by a set of lights.

```javascript
new DarkMask({ lights: [light1, light2, ...], color: 'rgba(0,0,0,0.9)' })
```

#### .compute(width, height)

will compute the dark mask.

#### .render(ctx)

will draw the computed dark mask on **ctx** canvas 2d context.

### about compute and render

Both Lighting and DarkMask objects have `compute()` and `render()` methods.

We think that **you** know the best when to recompute the lights because it’s closely link to the application you are making (we will not check at each time if something has changed, you know it).  
Call the `compute()` method when something has changed in your scene so we can recompute lights and shadows.

## <a id="underthehood"></a> How does it work under the hood?

_Illuminated.js_ divides its work into several layers.

### Real-time example

<iframe src="http://gre.github.io/illuminated.js/howdoesitwork.html" border="0" height="2700" width="450"></iframe>

### The art of composing layers

The layers are all stored in a Canvas which allows us to cache it. The light is drawn using a Canvas Radial Gradient in a cache canvas only once. This is interesting because canvas gradient are processor intensive  
At the end, layers are combine on the global canvas with `drawImage`.  
But the library lets you reuse these layers to combine them the way you want.

Canvas’ `globalCompositeOperation` is very useful to compose layers together.  
For instance, in the following example, the “Light shadow casting” layer is combined with the “Light rendering” layer to generate the “Light rendering with shadows” layer. The composition mode used is “destination-out” which remove the color of the destination image where the source image has color.

```javascript
light.render(ctx);
ctx.globalCompositeOperation = "destination-out";
this.cast(ctx);
```

Another very useful composite operation is `"lighter"` which adds color values. It is used to combine two lightings.

### How shadows are projected

Some rendering engine use [ray tracing][8] to render a scene, a concept very close to physics which trace from a light source a lot of rays with different paths which will collide with object and will be subject of absorption/diffraction/reflexion in accordance with the object properties…  
Ray casting is a very **realistic** rendering solution **but consuming** (you need a lot of rays to avoid noises in the result image).  
_Illuminated.js_ doesn’t use ray tracing because it aims to be efficient for a real-time usage. It uses some heuristics for casting shadows.

#### Let’s see how shadows are projected for a polygon object.

We have a scene with a light and a triangle.

![][9]

We select each edge of the polygon which is visible by the light (and in the light bounds).

![][10]

For every selected edge, we project it to generate a polygon area.

> **N.B.** In the current implementation, we generate an hexagon projection to ensure it goes outside of the light bounds because a quadrilateral didn’t garantee it, if a light is very close to it. The projecting vector used is enough big to work for most case, but it’s still an heuristic.

![][11]

We draw black color in this polygon area. Some improvments can be made by not drawing black in the shape / ajusting the opacity of the color.

![][12]

For casting blured shadows, we repeat this algorithm for each “samples” of the light. Samples are distribute around the light with a [“spiral algorithm”][13].

![][14]

```javascript
var GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5));
Lamp.prototype.forEachSample = function (f) {
  for (var s = 0; s < this.samples; ++s) {
    var a = s * GOLDEN_ANGLE;
    var r = Math.sqrt(s / this.samples) * this.radius;
    var delta = new Vec2(Math.cos(a) * r, Math.sin(a) * r);
    f(this.position.add(delta));
  }
};
```

## To be continued…

The current version of _Illuminated.js_ needs more work, I’m aware of some bugs and some parts I need to improve:

- Implementing new kinds of lights like “Spot”, “Neon”, …
- The dark mask doesn’t follow the Lamp orientation.
- The shadow casting of Circle objects are not projected nicely, I need to compute [tangent lines to the circle][15].
- Shadows go sometimes wrong especially when having objects behind objects
- The shadow sampling implementation is a bit hacky and wrong (changing the samples parameter changes the shadow opacity…)

## Get involved

[Try the editor][2] and [Get the source code][3].

This article is translated to [Serbo-Croatian](http://science.webhostinggeeks.com/masina-za-renderovanje) language by Jovana Milutinovich from Webhostinggeeks.com.

Illuminated.js is designed to add some awesome effects to your existing applications. Adding a cool atmosphere for your applications and games can make the difference!

Illuminated.js – 2D lights and shadows rendering engine for HTML5 applications

[2]: http://gre.github.io/illuminated.js/
[3]: https://github.com/bgrins/spectrum
[4]: http://www.w3.org/TR/css3-color/

<img src="/images/2012/05/color-alpha-options.png" alt="" class="thumbnail-left" />

I’m currently working on the User Interface of a scene editor for my [Illuminated.js library][2] with some color and alpha picker.

HTML5 now have the `<input type="color" />` and `<input type="range" />` which is nice. It works on Chrome and there are some [polyfills][3] to make it working on older browsers.

We will now see how we can easily **retrieve a rgba color from such an UI**, regardless of the color format given by the color picker and **combine the alpha component from the alpha range picker**.

> We can implement an **anythingToRGBA converter** in 10 lines of Javascript!

## What?

Basically, for instance, you have this: `"#ff6432"` and `0.8`

and you want this: `"rgba(255,100,50,0.8)"`

which is this color: <span style="background: #ff6432; display: inline-block; width: 50px">&nbsp;</span>.

> Well, of course, we could use a library with regexp parsers!

But there is a lot of different formats available especially if you want to convert a color from [CSS][4]!

Only for the <span style="color:blue">blue</span> color, you have at least 7 different representations: `#00F`, `#0000FF`, `rgb(0,0,255)`, `rgba(0,0,255,1)`, `hsl(255,100%,50%)`, `hsla(255,100%,50%,1)`,  
and… `blue`!

> Ouch, so let’s make a huge converter library!

Nope!

All of these are color formats are supported by CSS and also Canvas.  
**So, why not just re-using what the browser can do?**



## How?

Because we have access to Canvas in Javascript, **we can implement an anythingToRGBA converter in a few line of Javascript**:

```javascript
var getRGBA = (function(){
  var canvas = document.createElement("canvas");
  canvas.width = canvas.height = 1;
  var ctx = canvas.getContext("2d");
  return function (color, alpha) {
    ctx.clearRect(,,1,1);
    ctx.fillStyle = color;
    ctx.fillRect(,,1,1);
    var d = ctx.getImageData(,,1,1).data;
    return 'rgba(' [ d[], d[1], d[2], alpha ] ')';
  }
}());
```

You have now a ready to use Javascript color library!

`getRGBA("#ff6432", 0.8)` will returns `"rgba(255,100,50,0.8)"`.  
`getRGBA("red", 0.5)` will returns `"rgba(255,0,0,0.5)"`.

You can “standardize” your color and use it anywhere!

**Feel free to adapt the code to any other desired format.**

We can easily make the reverse (give a rgba color and get the #RRGGBB and alpha values):

```javascript
var extractColorAndAlpha = (function(){
  var canvas = document.createElement("canvas");
  canvas.width = canvas.height = 1;
  var ctx = canvas.getContext("2d");

  function toHex (value) {
    var s = value.toString(16);
    if(s.length==1) s = "0" s;
    return s;
  }

  return function (color) {
    ctx.clearRect(,,1,1);
    ctx.fillStyle = color;
    ctx.fillRect(,,1,1);
    var d = ctx.getImageData(,,1,1).data;
    return {
      color: "#" toHex(d[]) toHex(d[1]) toHex(d[2]),
      alpha: Math.round(1000*d[3]/255)/1000
    };
  }
}());
```

We can implement an anythingToRGBA converter in 10 lines of Javascript!

HTML5 Canvas as a color converter

**Did you know browsers now have a built-in HTML tag for making progress bar?**

<progress style="width: 50%">(progress is not supported)</progress>

How cool is that!

It is perfect for making web applications loading bar in just one line of HTML and a few Javascript code.

A progress tag will be displayed on recent browsers with a OS-native progress bar representing a loading. Like many HTML tag, if it is not supported, it fallbacks nicely by displaying its inner content. This fallback content should either be your own designed progress bar or simply display a percentage.

It is today supported by Firefox 9 , Chrome, Opera and IE10.



## Example

```html
<progress value="23" max="100">23 %</progress>
```

### On your browser:

<progress value="23" max="100">23 %</progress>

### On Linux / Firefox (with GNOME)

![](/images/2012/04/progress.png)

### On Mac OS / Chrome:

![](/images/2012/04/progress_mac.png)

### On IE 6:

![](/images/2012/04/progress_ie.png)

## Let’s see some cases:

### waiting

<progress max="1000"></progress>

```html
<progress max="1000"></progress>
```

### starting

<progress value="0" max="1000"></progress>

```html
<progress value="0" max="1000"></progress>
```

### in progress:

<progress value="500" max="1000"></progress>

```html
<progress value="500" max="1000"></progress>
```

### finished:

<progress value="1000" max="1000"></progress>

```html
<progress value="1000" max="1000"></progress>
```

## Making a download bar

When you need to load big resource like images, videos, or 3D materials, you usually want to display the progress of the download.  
You could still do it using some divs and CSS Javascript, but this is now much simpler to use a :

### One line of HTML:

```html
<progress id="download"></progress>
```

### And the Javascript:

(for more convenience, we are using jQuery)

```javascript
var totalBytes = 10000000; // CHANGE ME WITH THE SIZE OF THE RESOURCE
var req = new XMLHttpRequest();
var progress = $('#download');
progress.attr("max", totalBytes);
req.addEventListener("progress", function (e) {
  progress.attr("value", e.loaded).text(Math.floor(100*e.loaded/totalBytes) " %");
}, false);  
req.addEventListener("load", function (e) {
  // THE RESOURCE IS LOADED
  progress.replaceWith("Downloaded!");
});
req.open("GET","resource.dat",true);
req.send();
```

It is quite easy to extend my code to support multiple files to download.

It is also easy to use this progress bar for anything else, but remember it represents a progress. If you want to represent some kind of stats, refer to the dedicated tag.

A progress tag will be displayed on recent browsers with a OS-native progress bar representing a loading.

Work in <progress />

#

A long time ago, video games were only two-dimensional. Of-course this was due to our poor hardware capabilities, but when computers became faster and faster 3D games appeared in mass.  
**Did it kill 2D games? Nope.** They continue to exist because it offer a different gameplay and are easier to make. Maybe also a bit because we are nostalgic of old-school games!

We can distinguish two kinds of 2D games:

<img src="/images/2012/04/bomberman93.jpg" alt="" class="thumbnail-left" />
[**Tile based games**][2] where the game world is simplified with a big grid – each grid position has some properties.  
A map editor is not always needed for tile based games, because the map can be straighforward to represent and maintain like in a *Bomberman* or in a *Pacman*. A simple editor is generally used to make graphism with sprites.

[2]: http://www.tonypa.pri.ee/tbw/tut00.html
[4]: http://higherorderfun.com/blog/2012/05/20/the-guide-to-implementing-2d-platformers/
[5]: http://www.masswerk.at/JavaPac/JS-PacMan2.html
[6]: http://impactjs.com/documentation/weltmeister
[7]: http://gre.github.io/blazing-race
[12]: http://gre.github.io/blazing-race/maps/converter/

<br style="clear:both" />

<img src="/images/2012/04/woarpc001.jpg" alt="" class="thumbnail-left" />
**Non-tile based games**, which can be called “polygon based games” are more complex.  
In such game, like a *Worms* or a *Sonic*, it’s totally crazy to write the map by hand (objects positions, polygons coordinates, …). The alternative, is not to use predefined maps, but on-the-fly generated maps which doesn’t fit every games.

<br style="clear:both" />
  
[Here are more detailed work on these different game designs][4].

**Making the game engine** is one thing, but **designing the game levels** can be one big work too and **we need tools to make it easier**.



## Tile based game maps

In tile based games, maps are usually quite simple to represent.

For instance, here is how we can code the maze of [Pacman][5]:

```javascript
[
  "ahhhhhgxbhhdxehhhhhc",
  "vp....o......o....pv",
  "v.lhm...lhhm...lhm.v",
  "v.....n......n.....v",
  "v.n.n.v.ahhc.v.n.n.v",
  "d.v.o.v.vxxq.v.o.v.b",
  "x.v...v.vxxt.v...v.x",
  "c.bhm.o.bhhr.o.lhd.a",
  "v........x.........v",
  "em.lc.am.lm.lc.am.lg",
  "v...v.v......v.v...v",
  "v.k.o.o.lhhm.o.o.k.v",
  "vp................pv",
  "bhhhhhcxahhcxahhhhhd",
];
```

where every character is a tile and has a given meaning.

For more complex games, we can also represent the map with a set of objects, and each object has position and size properties (x, y, width, height) and other properties for the game logic.

For instance, see the _ImpactJS_ tile based games editor:

[![](/images/2012/04/weltmeister-tutorial-entities.png)][6]

## But what about polygons based game?

Well, some have tried to make dedicated 2D game map editor like shown in this video:

<iframe width="640" height="360" src="http://www.youtube.com/embed/kvvEmm2Vyoc?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

but it sounds a bit unfinished and specific.

### Do it yourself, but don’t reinvent the wheel.

**But finally, isn’t it what a 3D editor is doing?**

Isn’t it the most generic tool we can find?

They have done a lot of awesome work in term of user interface, polygon modeling, textures (procedural / bitmap), …let’s profit of all this work to generate awesome texture map while exporting polygons.

Relying on such tools, you don’t have to learn a brand new map editor, you can relax on what you know if you have the chance to know Blender or Maya or anything.

### The Z magic

Let’s ignore the Z dimension, or rather, let’s **use the Z-dimension as a way to represent the semantics of the game map!**

This is the map I made for [Blazing Race][7], a HTML5 against-the-clock platform game where you control a fireball:

![](/images/2012/04/zs.png)

For my game needs, I used **different Z layers to represent different kind of materials and game objects**:

- z=1 : candles’ position – the objective of the game is to light them all
- z=0 : the game grounds – where collision occurs
- z=-1 : the water areas – where your flame dies
- z=-2 : special areas where you miss oxgyen – your flame dies in a few seconds

But I also used **objects ids** as an another way to distinguish objects:  
a “start” object to define the game start position and two “topleft” and “bottomright” objects to define the game bound.

### Maintain your map source in one file

Another powerful feature of this, is you can maintain your map polygons AND your map textures in a single way. Use your 3D editor as a polygon editor and use its render engine to generate textures:

![](/images/2012/04/map1.png)

Take benefits from what your 3D editor can do.

### Export polygons to the Javascript game

![](/images/2012/04/path4850.png)

I’ve made a transformer which take a COLLADA file in input (the most commonly supported standard format to describe a 3D scene, you can export it from any 3D editor like Blender, Maya, 3DS…) which extract and transform relevant informations from it and give you a json map for your game in output.

_It was quite simple to implement, thanks to the Three.js COLLADA importer!_

Here is the current (unfinished) interface for this:

[![](/images/2012/04/demo_screenshot.png)][12]

As a proof of usability of the output JSON map, the preview was only made in a few lines of Javascript code.

Extract:

```javascript
function draw(map) {
  var container = $("#viewport").empty();
  $("#legend").empty();
  a = 0;
  var w = 500;
  var h = Math.floor((w * map.height) / map.width);
  var CROSS_SIZE = 3;
  var canvas = $('<canvas width="' + w + '" height="' + h + '"></canvas>');
  var ctx = canvas[0].getContext("2d");
  for (var name in map) {
    var objs = map[name];
    if (objs[0] && objs[0].faces) {
      var color = randomColor(70, 0.8);
      ctx.fillStyle = color;
      for (var i = 0; i < objs.length; ++i) {
        var obj = objs[i];
        for (var f = 0; f < obj.faces.length; ++f) {
          var face = obj.faces[f];
          ctx.beginPath();
          for (var v = 0; v < face.length; ++v) {
            var vertice = obj.vertices[face[v]];
            var x = (ctx.canvas.width * vertice.x) / map.width;
            var y = ctx.canvas.height * (1 - vertice.y / map.height);
            if (v == 0) ctx.moveTo(x, y);
            else ctx.lineTo(x, y);
          }
          ctx.fill();
        }
      }
      addLegend(color, name, true);
    }
  }
  for (var name in map) {
    var objs = map[name];
    if (objs[0] && objs[0].x) {
      var color = randomColor(50);
      ctx.strokeStyle = color;
      ctx.lineWidth = 2;
      for (var i = 0; i < objs.length; ++i) {
        var p = objs[i];
        var x = (ctx.canvas.width * p.x) / map.width;
        var y = ctx.canvas.height * (1 - p.y / map.height);
        ctx.beginPath();
        ctx.moveTo(x - CROSS_SIZE, y);
        ctx.lineTo(x + CROSS_SIZE, y);
        ctx.moveTo(x, y - CROSS_SIZE);
        ctx.lineTo(x, y + CROSS_SIZE);
        ctx.stroke();
      }
      addLegend(color, name, false);
    }
  }
  container.append(canvas);
}
```

## What is next?

Blazing Race, is not finished yet, I need to improve a lot of things.

I’ll try to release a standalone version of this converter soon with tutorials and examples.

Here is how you can design and export your 2D game map with Blender (both the logic and the graphics).

Blender as a 2D game level editor – Proof Of Concept

One week ago, I’ve released a [technical web experiment][1] featuring **a collaborative real-time Paint-like application I’ve called Play Painter**. It has been made with [Play Framework 2][2] and rely on WebSocket and HTML5 Canvas Javascript APIs.

[1]: /2012/03/30-minutes-to-make-a-multi-user-real-time-paint-with-play-2-framework-canvas-and-websocket/
[2]: http://playframework.org/
[4]: https://github.com/playframework/Play20/wiki/Iteratees
[5]: https://github.com/gre/playpainter/blob/master/scala/app/controllers/Application.scala
[6]: http://github.com/gre/playpainter
[7]: http://playpainter.greweb.fr/
[8]: https://github.com/gre/playpainter/issues/1
[9]: https://twitter.com/dbathily

Thanks to everyone having tested my Play Painter experiment, you helped me figure out bugs and bottlenecks and to benchmark the application running on my tiny server.  
The first version of Play Painter has been improved with some optimizations.

Explanation…

<blockquote class="twitter-tweet" lang="fr"><p>Thanks guys for testing playpainter! but you are breaking my server :D <a href="http://t.co/F62qwk1i" title="http://twitter.com/greweb/status/179194592481116160/photo/1">twitter.com/greweb/status/…</a></p>&mdash; greweb (@greweb) <a href="https://twitter.com/greweb/status/179194592481116160">12 mars 2012</a></blockquote>



## In brief

- **80 twitts**, **3500 unique visitors** in a few days.
- a peak of about **80 simultaneous painters**.
- about **200 WebSocket messages per second** when 3-4 users are drawing => bottleneck found.
- when it occurs, 100% CPU and about **1500 system interrupts per second** on my poor Atom 1.2 Ghz server.

## Some reasons

The initial version of Play Painter was a basic fast-prototyped version:

First, It was **spreading every mouse events** (down, up, move) to all clients **as fast as it comes**. It means that, depending on the computer and browser performance, a huge number of events could have been triggered and spread to all connected users.

We solved this by **Chunking draw events**.

Second, **a lot of informations was repeated in WebSocket messages.** No datas were stored on the server-side so to be sure a new user see the right draws, player name, brush color and size was sent in every message. Multiply this by the number of mouse events and you get a lot of useless information!

We are now **Storing painters information**.

## Chunking draw events

When an user starts drawing, mouse events give the brush positions (x, y). But instead of sending a websocket message for each of these new positions, they are stored, and every **X** milliseconds, are sent in a websocket message. Such message contains all points of the draw from the last sent draw message.

The **X** value has currently been fixed to **50 milliseconds** because it’s enough for the human eye: It means about 20 messages per second for one painter. In movies we usually have a 24 frame rate.

The same principle has been applied on the painter brush positions.

### Example

**Before**  
13 WebSocket messages:

```javascript
{"type":"lineTo","x":181,"y":259,"pid":19}
{"type":"lineTo","x":183,"y":259,"pid":19}
{"type":"lineTo","x":184,"y":257,"pid":19}
{"type":"lineTo","x":187,"y":257,"pid":19}
{"type":"lineTo","x":188,"y":257,"pid":19}
{"type":"lineTo","x":191,"y":256,"pid":19}
{"type":"lineTo","x":192,"y":255,"pid":19}
{"type":"lineTo","x":192,"y":255,"pid":19}
{"type":"lineTo","x":192,"y":254,"pid":19}
{"type":"lineTo","x":193,"y":254,"pid":19}
{"type":"lineTo","x":195,"y":254,"pid":19}
{"type":"lineTo","x":196,"y":253,"pid":19}
{"type":"lineTo","x":196,"y":253,"pid":19}
```

**After**  
2 WebSocket messages: (50 ms apart)

```javascript
{"type":"trace","points":[{"x":181,"y":259},{"x":183,"y":259},{"x":184,"y":257},{"x":187,"y":257},{"x":188,"y":257},{"x":191,"y":256},{"x":192,"y":255}],"pid":19}
{"type":"trace","points":[{"x":192,"y":255},{"x":192,"y":254},{"x":193,"y":254},{"x":195,"y":254},{"x":195,"y":253},{"x":196,"y":253},{"x":196,"y":253}],"pid":19}
```

### To a variable frame rate?

I am also thinking about a variable rate depending of the number of active painters. In fact, the more we have painters, the more we will have messages, and the more the server will have system interrupts, we could then decrease the frame rate per second to reduce this load.

The problem of this extreme approach is the degradation of the feeling of real-time.

For now, I’m keeping the constant frame rate version, we will see how far it goes.

## Storing painters information

As I said, **a lot of informations was repeated in WebSocket messages.** In every draw events, painter name, brush size and brush color was sent from the client to the server, and the spread into all connected clients.

This was ok for prototyping but we have now optimize this by storing these painter generic informations in the server and sending them when a new WebSocket connection is opened.

### Example

This is what a client can receive when a websocket is connected:

```javascript
{"type":"youAre","pid":24}
{"name":"john","color":"red","size":5,"type":"painter","pid":21}
{"name":"gre","color":"red","size":5,"type":"painter","pid":24}
{"name":"peter","color":"red","size":5,"type":"painter","pid":4}
{"name":"paul","color":"red","size":5,"type":"painter","pid":6}
{"name":"jack","color":"red","size":5,"type":"painter","pid":2}
```

and then…

```
{"type":"trace","points":[{"x":181,"y":259},{"x":183,"y":259},{"x":184,"y":257}],"pid":19}
...
```

By knowing all painter properties, when someone will draw something, he will not have to repeat which color and size its brush has.

### Server side

It was quite interesting to implement the server part with [Play2′s Iteratees][4], a new way of handling I/O – not so new in fact because it is directly related to Haskell Iteratee concepts.

To implement a WebSocket connection, you will provide an **Iteratee** for consuming the **input** and an **Enumerator** for producing the **output**.

Enumerator are chainable, this is how I firstly send the painter id and painters informations:

```scala
// out: handle messages to send to the painter
val out =
  // Inform the painter who he is (which pid, he can them identify himself)
  Enumerator(JsObject(Seq("type" -> JsString("youAre"), "pid" -> JsNumber(pid))).as[JsValue]) >>>
  // Inform the list of other painters
  Enumerator(painters.map { case (id, painter) =>
    (painter.toJson JsObject(Seq("type" -> JsString("painter"), "pid" -> JsNumber(id)))).as[JsValue]
  } toList : _*) >>>
  // Stream the hub
  hub.getPatchCord()
```

The **>>>** operator is a shortcut to the **andThen** method which is the way to chain enumerators.

For more details, [see the scala code of the controller][5].

## Other features

The application has been improved in many other ways.

- **A “buffering” Canvas** in the foreground has been add **for the user draws**. It brings client-side reactivity and helps to avoid unpleasant lag feeling when drawing. When the user draw events are coming from the server and no other user events has been sent since, it’s synchronized and we can clean this buffer.
- **Painter positions are show with their names**.
- It should now work properly on **smartphones and tablets**. Try on iPad and iPhone, and maybe on recent version of Android (WebSocket support required).
- **Keyboard shortcut**: using arrows to change brush size and color.
- The **[source code][6] has been polished and commented** especially the server side part (it’s probably the hardest part if you don’t know Play framework).
- Error message displayed when a technology is not supported and when the WebSocket connection goes down (with a reconnecting try loop).

## The demo is still online!

**[playpainter.greweb.fr][7]**

## Future

With these two optimizations, I’ve reduce the global **number of socket messages** and also the **size of each message**.

The first benchmark sounds good, 3 painters was simultaneously crazily painting while the server application was only using less than 10% of CPU.

Now, the most challenging part would be to scale the application to a huge number of connections, but having maybe solved this bottleneck, it’s maybe now more a matter of system architecture than the application itself.

This experiment gave me a lot of interest in **WebSocket** and also in **the powerful way WebSockets are handled in Play framework**.

If anyone want to start a Java version of the application, please go on! [(this was requested on Github)][8]

Thanks to [@dbathily][9], we know have both Scala and Java version!

### Next experiment

I am thinking about making a multiplayer game on the web.  
It would be something like a shooter survival game (like Counter Strike Zombie Mod) a multi-plateform 2D side view game (like Mario) !

You will know more about this soon!

One week ago, I’ve released a web experiment featuring a collaborative Paint-like application made with Play Framework 2 and relying on WebSocket and HTML5 Canvas. Here is how I've improved it.

Play Painter – how i've improved the 30 minutes prototyped version

[1]: http://playpainter.greweb.fr/
[2]: http://playframework.com
[3]: http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html
[4]: http://dev.w3.org/html5/websockets/
[5]: /2012/03/play-painter-how-ive-improved-the-30-minutes-prototyped-version/
[6]: https://github.com/gre/playpainter

[  
<img src="/images/2012/03/playpainter_teaser2.png" alt="" class="thumbnail-left" />
][1]

> I will show you how to **implement a multi user paint** using latest web technologies like [Play framework][2] (version 2), [HTML5 Canvas][3] and [WebSocket][4].

Let’s see how to implement this from scratch in about 30 minutes…

<iframe width="640" height="360" src="http://www.youtube.com/embed/NHEbm-WEbRw?feature=player_embedded" frameborder="0" allowfullscreen></iframe>



[and read how I’ve improved this initial version…][5]

[or try the demo below…][1]

<iframe frameborder="0" src="http://playpainter.greweb.fr/" width="550" height="501" style="overflow: hidden; max-width: 550px"></iframe>

[Fork me on Github.][6]

[VIDEO] I will show you how to implement a multi user paint using latest web technologies like Play framework (version 2), HTML5 Canvas and WebSocket.

30 minutes to make a multi user real time paint with Play 2 framework, Canvas and WebSocket.

#

<img src="/images/2012/02/wrong-chart-scale.png" class="thumbnail-left" />

If you have ever made a chart library in your life, you’ve probably asked yourself how to find the best scale for the grid in order to have **nice values to display in the axis**.

Most of the time, **data ranges are unknown**, hence we need to **adapt the grid step** to provide the best display.

## Check this out

<iframe src="/demo/grid-utils/" frameborder="0" width="525" height="140"></iframe>

Let’s explain the algorithm…



## About scientific notation

Any number can be formatted in scientific notation. It is written in the form of **A x 10N** and is noted **AeN**.

For instance, 2300 becomes **2.3e3** (because 2300 = 2.3 x 103), 12 becomes **1.2e1**, and 0.23 becomes **2.3e-1**.

Scientific notation is exactly made for **displaying huge or tiny values in a few characters**.  
We can use the same principle for finding good values for the step scale, we can just **keep the pow of 10** part (**N**) and **round the value part** (**A**).

## Magic numbers

But **rounding is not enough**, I have found that good pattern numbers of step range is those divisible by 2, 5 and 10.

In math term, we need to find a step range _sr_, where

```
∀ n ∈ |N, ∀ a ∈ {1, 2, 5}, ∃ sr, sr = a x 10^n
```

This is basically because 2 x 5 = 10 : using a step of 5 we have a 10 modularity every 2 step, and, using a step of 2 we have a 10 modularity every 5 step.

** 2 step:** 0 2 4 6 8 **10** 12 14 16 18 **20** …  
** 5 step:** 0 5 **10** 15 **20** 25 **30** 35 **40** 45 …  
**10 step:** **0 10 20 30 40 50 60 70 80 90** …

For any dataset, we need to fallback on the closest step range in all of possible step ranges: … 0.002, 0.02, 0.2, 2, 20, 200, …, … 0.005, 0.05, 0.5, 5, 50, 500, …, and … 0.001, 0.01, 0.1, 1, 10, 100, …,

### Calculate the pow of 10

To get the **N** value of the **A x 10N** form, we can use the log of 10:

```javascript
N = Math.log(number) / Math.log(10);
```

### Calculate the value modulo 10

To get the **A** value of the **A x 10N** form, we can just divide the number by **10N**:

```javascript
A = number / Math.pow(10, N);
```

### ‘Rounding’ the number

We know just need to change the value of **A** and make it more “readable”.  
We can map the value as follow:

```
if A ∈ [0, 1.5[ then A becomes 1
if A ∈ [1.5, 3.5[ then A becomes 2
if A ∈ [3.5, 7.5[ then A becomes 5
if A ∈ [7.5, 10[ then A becomes 10
```

Note that these rules may probably be improved, I would love if someone could improve this (because I use a arithmetic mean approach and it should probably be arithmetic).

## Implementation

### Scala

<script src="https://gist.github.com/1987311.js?file=GridUtils.scala"></script>

### Javascript

<script src="https://gist.github.com/1987311.js?file=GridUtils.js"></script>

**Usage example:**

```javascript
GridUtils.findNiceRoundStep(xMax, 10);
```

where _xMax_ is the scale of the axis, and _10_ is the desired number of graduation split.

## Conclusion

Finding the best grid step is finally a simple thing to implement but is an essential feature every chart libraries should have.

If you have ever made a chart library in your life, you’ve probably asked yourself how to find the best scale for the grid in order to have nice values to display in the axis.

Chart libraries headaches – finding the best grid step

[1]: /images/2012/02/Capture-d’écran-2012-02-29-à-11.26.01.png "Bezier example"
[2]: /images/2012/02/TimingFunction.png
[3]: http://13thparallel.com/archive/bezier-curves/
[4]: http://en.wikipedia.org/wiki/Newton%27s_method
[5]: http://en.wikipedia.org/wiki/Dichotomic_search
[6]: http://sliderjs.org/
[7]: http://en.wikipedia.org/wiki/Inventor's_paradox
[8]: /2012/02/bezier-curve-based-easing-functions-from-concept-to-implementation/ "Bezier Curve based easing functions – from concept to implementation"

> **EDIT 2014:** This article ends up in an updated library available on [NPM](http://npmjs.org/package/bezier-easing) (`bezier-easing`) and available on [Github](https://github.com/gre/bezier-easing). It has been used by Apple for the [mac-pro page](http://www.apple.com/mac-pro/) and by [Velocity.js](http://velocityjs.org/). You can also find its usage in the [glsl-transition examples](http://greweb.me/glsl-transition/example/).

<img src="/images/2012/02/bezier_transition_editor.png" class="thumbnail-left" />

Many animation libraries are today using **easing functions** – functions of time returning a progression percentage value. This is required to perform such cool effects:

<iframe src="/demo/simple-easing-animation/" height="50" width="50%"></iframe>

But most of these libraries implement a huge collection of functions. We will see how we can generalize them with bezier curves.



For instance, we use to do this:

```javascript
EasingFunctions = {
  linear: function (t) {
    return t;
  },
  easeInQuad: function (t) {
    return t * t;
  },
  easeOutQuad: function (t) {
    return t * (2 - t);
  },
  easeInOutQuad: function (t) {
    return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
  },
  easeInCubic: function (t) {
    return t * t * t;
  },
  easeOutCubic: function (t) {
    return --t * t * t + 1;
  },
  easeInOutCubic: function (t) {
    return t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
  },
  easeInQuart: function (t) {
    return t * t * t * t;
  },
  easeOutQuart: function (t) {
    return 1 - --t * t * t * t;
  },
  easeInOutQuart: function (t) {
    return t < 0.5 ? 8 * t * t * t * t : 1 - 8 * --t * t * t * t;
  },
  easeInQuint: function (t) {
    return t * t * t * t * t;
  },
  easeOutQuint: function (t) {
    return 1 + --t * t * t * t * t;
  },
  easeInOutQuint: function (t) {
    return t < 0.5 ? 16 * t * t * t * t * t : 1 + 16 * --t * t * t * t * t;
  },
};
```

Defining such functions is lot of math fun but it is very **specific** and not really customizable. Hopefully, we can generalize these easing functions. With **Bezier curves**.

In fact, this work has already been done in CSS Transitions and CSS Animations specifications! You can use `transition-timing-function` CSS property and give a `cubic-bezier(x1, y1, x2, y2)` value (all **ease, linear, ease-in, ease-out, ease-in-out** values are just fallbacking on this cubic-bezier usage).

![][2]

In a bezier curve based easing function, the X axis is the **time axis** whereas the Y axis represents the **percentage of progress** of the animation.  
The two points P1 and P2 are called **handles** and you can (exclusively) control their X and Y positions to generate every possible cubic timing function.

### Live demo

Try to interact with the handles:

<iframe src="/demo/bezier-easing/" frameborder="0" width="560" height="400"></iframe>

## Implementation

Ok, so, this bezier curve concept is great but how can I implement it?

I’ve read [here][3] how simple is it to **compute many points of a Bezier curve** and potentially draw them:

```javascript
function B1(t) {
  return t * t * t;
}
function B2(t) {
  return 3 * t * t * (1 - t);
}
function B3(t) {
  return 3 * t * (1 - t) * (1 - t);
}
function B4(t) {
  return (1 - t) * (1 - t) * (1 - t);
}
function getBezier(percent, C1, C2, C3, C4) {
  var pos = new coord();
  pos.x =
    C1.x * B1(percent) +
    C2.x * B2(percent) +
    C3.x * B3(percent) +
    C4.x * B4(percent);
  pos.y =
    C1.y * B1(percent) +
    C2.y * B2(percent) +
    C3.y * B3(percent) +
    C4.y * B4(percent);
  return pos;
}
```

But it’s not enough. We need to project a point to the Bezier curve, in other words, we need to get the Y of a given X in the bezier curve, and we can’t just get it with the `percent` parameter of the Bezier computation.  
**We need an interpolation.**

### Deep into Firefox implementation

In Mozilla Firefox, The bezier curve interpolation is implemented in nsSMILKeySpline.cpp : .

What we can learn from it is:

- A first optimization store **sample values of the bezier curve** in a small table used to roughly find a initial X guess.
- Then, it use two different implementation strategies: One use the [Newton’s method][4] and the other is just a [dichotomic search][5] (binary subdivision).
- A **criteria** based on the **slope** give the best strategy to take.

These sub-optimizations probably make the difference for the C++ version but are not really relevant for the JavaScript implementation. Moreover, I have only used the Newton’s method algorithm.  
And this is the code:

<script src="https://gist.github.com/1926947.js?file=KeySpline.js"></script>

Now we can just alias some classic easing function – like CSS does.

<script src="https://gist.github.com/1926947.js?file=EasingFunctions.json"></script>

I’m working on the next version of [Slider.JS][6] which relies on 3 different technologies for image transitions: **CSS Transitions**, **Canvas** and **GLSL shaders (from WebGL)**.

---

I have now found **a common way to describe easing functions for both CSS-based and Javascript-based animations**!

This example has shown that sometimes, finding a larger solution for a problem is more interesting than having specific solutions.  
**This is called the [Inventor’s paradox][7].**

Many animation libraries are today using easing functions – functions of time returning a progression percentage value. We will see how we can generalize them with bezier curves.

Bezier Curve based easing functions – from concept to implementation

[2]: http://sliderjs.org/
[3]: http://www.ubelly.com/2011/11/scalablejs/

<img src="/images/2012/02/218px-Mir_diagram-fr.svg_.png" alt="" class="thumbnail-left" />

In this article, we will focus on the power of **CSS as a descriptive language**, current template system approach and their problems with **modularity** and **extensibility**, and try to mix both features from the **concept** to a **concrete implementation**.



<br style="clear: both" />

## What is CSS ?

CSS is an extremely powerful descriptive language.  
It helps to define **how to display a document** (e.g. a web page).

A style sheet contains a set of **CSS rules**.  
Each CSS rule has a **CSS selector** associated with a set of **declarations**.  
You can see a CSS selector as a selection filter applied on every HTML element. A few element can match a CSS selector if they fit the structure describes in this selector.  
Each **declaration** is composed of a couple (**property** : **value**).  
The **CSS property** is a predefined property related to a display or layout behavior.  
The **value** will apply a custom value for the property on all elements matching the CSS selector.

Let’s focus on some advantages of this descriptive language:

### A CSS rule is independant from others.

The order of CSS rules _(selector declarations)_ **really** does not matter.  
The priority between CSS rules is based on the selector itself and not on their arrangement.

### You can “mix” CSS rule

2 CSS rules can have the same CSS selector. An element can be matched with multiple CSS rules. CSS rules are merged, it’s called the cascading.  
This is the most important feature of CSS.  
It implies a very modular and extensible language.

#### Example

```css
a {
  color: #33CC00;
  text-decoration: none;
}
a:hover { text-decoration: underline; }
#articles {
  font-size: 12px;
}
#articles a {
  color: red; /* overriding the generic color of a */
}
```

## Some limitations of today’s template system

Most of template system are based on inherence between templates.

- You have usually an “inclusion” approach: a template will “include” multiple external template. _(Many template into Many template)_
- And an “extension” approach: You define in a main template an area where you can append a template. Others templates “extend” your main template. _(One main template for Many template)_

These approaches aims to factorize template codes and that’s great.

But it doesn’t fit my needs:

- It brings **dependencies between templates**.
- If you add a new template, you have to modify existing templates.  
  If your application tend to go modules based, this is going to be unmaintainable.

> **web application module (n)**  
> 1 : an independent unit of functionality that is part of the total structure of a web application

### A solution for scalable applications and libraries

I’ve recently started to rewrite my [SliderJS][2] library and I needed to split it into very modular features and having loose coupling between each component.

I followed this [Scalable JavaScript Application Architecture][3] article.

So, **how to bring loose coupling in templating?**.  
Each module have its own template and know where to append. Bringing this logic in a main template would break the independency and if I need to add new modules soon, it will not working without modifiyng it.  
How to keep the scalability of the main template without modifying it?

The best solution I found is to combine **CSS selectors** concepts with **template system** approaches.

## CSS concepts applied on templating

I’ve decided to inspire from CSS: **attaching a CSS selector with a template**.  
It benefits from some CSS advantages explained before.

### Simple twitter widget example

```html
<div class="twitter">
  <h1>Twitter</h1>
  <ul class="twitts">
    <li class="twitt">Hello world!</li>
  </ul>
  <footer><a href="http://twitter.com/greweb">Follow me on twitter</a></footer>
</div>
```

#### Classical approach

The way to template it with the classical approach would be:

```html
<div class="twitter">
  <h1>Twitter</h1>
  <ul class="twitts">
    {for twitt in twitts}
    <li class="twitt">{twitt}</li>
    {/for}
  </ul>
  <footer><a href="http://twitter.com/{me}">Follow me on twitter</a></footer>
</div>
```

#### CSS selector based approach

But we can also split the original “template” in small fragments and mix all of them.  
It helps to define each templates independently.

**We can identify:**

- A **root template fragment**:

```html
<div class="twitter"></div>
```

- A **header fragment** appended with `.twitter` selector and with an **high priority**:

```html
<h1>Twitter</h1>
```

- A **twitts list fragment** appended with `.twitter` selector:

```html
<ul class="twitts">
  {for twitt in twitts}
  <li class="twitt">{twitt}</li>
  {/for}
</ul>
```

with **parameters** `twitts = [ "Hello world!" ]`

- An empty **footer fragment** appended with `.twitter` selector and with a **low** priority:

```html
<footer></footer>
```

- A “follow me” **link fragment** appended with `.twitter footer` selector:

```html
<a href="http://twitter.com/{me}">Follow me on twitter</a>
```

with **parameters** `me = "greweb"`

### Advanced example

This is another example with a slider.

Let’s conceptually imagine the following template language:

```html
@root { html: <div class="slider"></div> }

.slider {
  html: <div class="slides"></div>
}

.slider div.slides {
  html: <canvas class="slides"></canvas>
}

.slider div.slides {
  html:
  <div class="slide">
    <a href="<%= link %>">
      <img src="<%= img %>" />
      <span class="caption"><%= title %></span>
    </a>
  </div>
}

.slider {
  priority: -10
  html: <div class="pager"></div>
}

.slider div.pager {
  priority: 10
  html: <a class="prevSlide" href="javascript:;">prev</a>
}

.slider div.pager {
  priority: -10
  html: <a class="nextSlide" href="javascript:;">next</a>
}

.slider div.pager {
  html: <span class="pages"></span>
}

.slider div.pager {
  html: <span class="pages">
    <% for (var i=0; i<slides.length; ++i) { %>
    <a class="page" href="javascript:;"><%= i+1 %></a>
    <% } %>
  </span>
}
```

combined with some parameters, it will result

```html
<div class="slider">
  <div class="slides">
    <div class="slide">
      <a href=".."><img src=".." /><span class="caption">...</span></a>
    </div>
    <div class="slide">...</div>
    <div class="slide">...</div>
    <canvas class="slides"></canvas>
  </div>
  <div class="pager">
    <a href="javascript:;" class="prevSlide">prev</a>
    <div class="pages">
      <a href="javascript:;" class="page">1</a>
      <a href="javascript:;" class="page">2</a>
      <a href="javascript:;" class="page">3</a>
    </div>
    <a href="javascript:;" class="nextSlide">next</a>
  </div>
</div>
```

Of-course we could also do this programmatically with DOM. But see the benefit of such a descriptive way to define things?

You should keep in mind that **the order of rules definition does not matter**. In that’s sense, it is **a mixable, extensible, modular and loosely-coupled template system**.

### More about this POC

Unlike CSS, **two same rules aren’t merged but are appended**.

The **_priority_** governs the order of append. The higher the value is, the sooner it is appended to the containers selected by the CSS selector.

As you can see, there is a **micro-templating** inside each rule. For this example, it looks like the John Resig ‘s Micro Templating.

Note also that a rule must be aware of its **parameters** to work properly. But this only concerns the implementation: You have to find a way to give a dynamic reference of these parameters when you add a rule.

### Concrete implementation

The code above was a conceptual proof of concept, but I implement a subset of these features in Javascript and made “SelectorTemplating.js” available here : <https://gist.github.com/1731611>

This is how it can be used for (almost) the same example. You will see different style of usage:

```javascript
var node = document.getElementById("slider");
var t = new SelectorTemplating(node);
var tmpl; // defined somewhere, the John Resig 's Micro Templating.

// root module
function root () { return '<div class="slider"></div>' }
t.add(null, root);

// slides module
var slidesTmpl = tmpl('<div class="slides"> <% if(obj.slides) { for(var i=0; i<slides.length; ++i) { var s = slides[i]; %> <div class="slide"> <a href="<%= s.link %>"> <img src="<%= s.img %>" /> <span class="caption"><%= s.title %></span> </a> </div> <% }} %> </div>')
var slides = [ ... ]; // mutable
t.add(".slider", function () { return slidesTmpl(slides: slides) });

// canvas module
t.add(".slider div.slides", function () { return '<canvas class="slides"></canvas>' });

// pager module
var pagesTmpl = tmpl('<div class="pager"> <span class="pages"> <% if(obj.slides) { for(var i=0; i<slides.length; ++i) { %> <a href="javascript:;" class="page"><%= i+1 %></a> <% }} %> </span> </div>');
var slides = [...]; // synchronised with the slides module
var prevButton, nextButton; // DOM element init when templated
var pages = function () {
  return pagesTmpl(slides: slides);
}
t.add(".sliderjs", pages, null, -10);
t.add(".sliderjs .options", function () { return '<a class="prevSlide" href="javascript:;">prev</a>' }, function (n) { prevButton = n[0] }, 10 }); // prepend first in options
t.add(".sliderjs .options", function () { return '<a class="nextSlide" href="javascript:;">next</a>' }, function (n) { nextButton = n[0] }, -10 }); // append at the end of options

// when all modules are init :
t.init();
```

```
t.add (selector, templateFunction, callback, priority)
 * selector is the selector function. if null, append to root.
 * a template function is an identifier in the template.
 * the callback is called at the end of the templating with 2 arguments : the appended nodes and the global container.
```

#### Algorithm of the template process

```
container := the container element
rules := an array containing all rules.
sort rules by priority.
(1) take one rule from rules
  - elements := []
  - if the selector is @root, elements := [container]
  - otherwise, elements := all elements which matches the selector
  - if the elements is empty, back to (1) by taking the next rule.
  - (2) if not, templatize the html and append it into all of these elements. remove the rule from rules. back to (1) by starting from the first rules.

the loop (1) must end when :
  - there is no rules anymore
  - you have covered all the rules array without finding a match (without passing by (2) for this loop). In that case, it means some rules are not used.
```

There is a known limitation of the algorithm I intend to fix soon:
Once we found matching elements for a rule, we append the template in these elements once, and we remove the rule. It’s a simple way to avoid recursion. But this approach doesn’t work if a selector can potentially matches elements defined in different rules. **I know how to fix this but it’s not yet implemented.**

## What's next?

We are working hard for the next version (v2) of [SliderJS](http://sliderjs.org) by trying to make a revolutionary IDE platform for SliderJS. It requires a modulification of every components of SliderJS, we try to keep things simple (no external library required, the core system is only 4k sized). You will have more information soon!

This templating system should benefits of this work.

Keep in touch!

In this article, we will focus on the power of CSS as a descriptive language, current template system approach and their problems with modularity and extensibility, and try to mix both features from the concept to a concrete implementation.

CSS-selector-based templating system for scalable JavaScript applications

[1]: http://playframework.org
[2]: http://aur.archlinux.org/packages.php?ID=45541
[3]: http://nginx.org
[4]: https://wiki.archlinux.org/index.php/Play_framework

This video shows how to run different instances of [Play framework][1] server in the most Linux friendly way: using daemons. Example with ArchLinux, using yaourt, the [playframework AUR package][2] and [nginx][3].

<iframe src="http://player.vimeo.com/video/30603225?title=0&amp;byline=0&amp;portrait=0" width="400" height="300" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

# Some links

- [Play framework website][1]
- [Play framework Archlinux documentation][4]
- [Play framework AUR package][2]



# Abstract summary

## Introduction

Existing Platform as a Service: [Playapps.net][5], [Heroku.com][6].

[5]: http://playapps.net
[6]: http://heroku.com

Our needs are quite different: you sometimes need to have your own server on your own infrastructure and not depending on third party web services.

Let’s see how to deploy some play applications from scratch with ArchLinux.

## Requirement

[Install ArchLinux on your server][7]

[7]: http://archlinux.org

[Install yaourt][8]

[8]: http://archlinux.fr/yaourt-en

## Installation

```bash
yaourt -S playframework
```

## Creating 2 play framework applications

```bash
mkdir sites && cd sites
play new app1
play new app2 # editing app/views/
```

## Configuring daemons

````bash
cd /etc/rc.d
ln -s skeleton_playapp app1
ln -s skeleton_playapp app2
cd /etc/conf.d
cp playapp_sample app1
cp playapp_sample app2
vim app1 # configure variables
vim app2 # configure variables
```bash

For app1 :

```bash
PLAY_APP=/home/gre/sites/app1
PLAY_USER=gre
PLAY_ARGS="--%prod --http.port=9001"
````

For app2 :

```bash
PLAY_APP=/home/gre/sites/app2
PLAY_USER=gre
PLAY_ARGS="--%prod --http.port=9002"
```

## Starting daemons

```bash
rc.d start app1
rc.d start app2
```

Make it permanent in /etc/rc.conf by adding them in the DAEMONS variable.

```bash
...
DAEMONS=(... app1 app2)
```

## Nginx, as a front end proxy server

Install nginx using pacman.

Edit `/etc/nginx/conf/nginx.conf`

```nginx
...
    server {
        listen 80;
        server_name app2.archdemo;
        location / {
          proxy_pass http://127.0.0.1:9002;
          proxy\_set\_header Host $host;
          proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;
          proxy\_set\_header X-Forwarded-Host $host;
          proxy\_set\_header X-Forwarded-Port $server_port;
          proxy\_set\_header X-Forwarded-Proto https;
        }
    }
    server {
        listen 80;
        server_name app1.archdemo;
        location / {
          proxy_pass http://127.0.0.1:9001;
          proxy\_set\_header Host $host;
          proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;
          proxy\_set\_header X-Forwarded-Host $host;
          proxy\_set\_header X-Forwarded-Port $server_port;
          proxy\_set\_header X-Forwarded-Proto https;
        }
    }
...
```

This video shows how to run different instances of Play framework server in the most Linux friendly way: using daemons. Example with ArchLinux, using yaourt, the playframework AUR package and nginx.

How to deploy your play applications on ArchLinux with daemons


[1]: http://gre.github.io/flexible-nav/demo
[3]: https://github.com/gre/flexible-nav

[4]: javascript:(function(){window.flexibleNavBase='http://gre.github.io/flexible-nav/lib/';var%20a=document.getElementsByTagName('head')[0],b=document.createElement('script');b.type='text/javascript';b.src=flexibleNavBase+'bookmarklet.min.js';a.appendChild(b);})();%20void%200

## [Demo][1]

> Flexible Nav is a small jQuery library which add a smart navigation bar on the right of the page. It improves a web page navigation and helps to visualize different sections of a document, an article,.. any web page.
>
> Nav links are distributed proportionally to the page sections. See how your scrollbar “weds” these links.

Flexible Nav is both a **library** and a **bookmarklet** which can be used easily in any website.

The bookmarklet demonstrate the **hackability of the web** by using the semantic of web headings (_h1, h2, h3, .._).

### Links

- [Documentation and Demos][1]
- [fork me on Github][3]
- [FlexibleNav bookmarklet][4] (drag me in your bookmarks bar)


Flexible Nav is a small jQuery library which add a smart navigation bar on the right of the page. It improves a web page navigation and helps to visualize different sections of a document, an article,.. any web page.

Improve your web navigation experience – Flexible Nav jQuery library

[1]: /2011/07/same-game-gravity-for-ipad-iphone-android-facebook-chrome-and-web/
[2]: http://gre.github.io/same-game-gravity
[4]: /2011/06/automating-web-app-development-for-multiple-platforms/
[5]: https://github.com/gre/same-game-gravity
[6]: https://github.com/gre/same-game-gravity/blob/master/game.html
[7]: https://github.com/gre/same-game-gravity/blob/master/game.css
[8]: https://github.com/gre/same-game-gravity/blob/master/game.js
[9]: https://github.com/gre/same-game-gravity/blob/master/game.js#L324
[10]: https://github.com/gre/same-game-gravity/blob/master/game.js#L687
[11]: https://github.com/gre/same-game-gravity/blob/master/game.js#L850
[12]: https://github.com/gre/same-game-gravity/blob/master/game.desktop.js
[13]: https://github.com/gre/same-game-gravity/blob/master/game.desktop.js#L137
[14]: http://docs.phonegap.com/phonegap_accelerometer_accelerometer.md.html
[15]: http://dev.w3.org/geo/api/spec-source-orientation.html
[16]: http://twitter.com/42loops
[17]: https://github.com/peutetre/test-mobile-safari/blob/master/devicemotionevent.html
[18]: /images/2011/07/c-rotation.png
[19]: https://github.com/gre/same-game-gravity/blob/master/game.desktop.js#L31
[20]: https://github.com/gre/same-game-gravity/blob/master/index.css#L35
[21]: http://playframework.org/
[22]: /images/2011/07/same_game_gravity_schema.jpg
[23]: http://same.greweb.fr/public/javascripts/same.scores.js

see also [Same Game Gravity presentation][1].

2 years ago, I started to developed the [Same Game][2] as an HTML Canvas experiment. I’ve enjoyed developing this game, mostly because playing with HTML5 Canvas is so easy. Recently I’ve seen a nice increase in the user base (now around 250 visitors a day) – despite it being perhaps the simplest games I’ve ever developed. Simplicity is good, but my increase in users is thanks to the power of HTML5: The Same Game is available for 6 different platforms. And I can pump out new builds for them all in around 15 minutes. Here’s how…

**It’s often the simplest games which work. Too much complexity is not good.**

[  
![](/images/2011/07/gravity_exemple.png)
][2]



In 2010, I learned how to make mobile web applications. It was also the year of the iPad. Out of interest I tried my same game canvas experiment on the iPad, and was surprised to find that it worked pretty well out of the box! Seeing it run on multiple devices was exciting – and the touch screens offered a new dimension for creating highly intuitive interactions. I mean, today, **even my mum can play Same Game Gravity without any help!** (That’s unfortunately not the case for her desktop)

That’s why I wanted to make Same Game for mobile. I started out developing and testing it as an Android application – because I have an Android phone. I created my own micro framework with some MVC concept (views, controllers, a router, etc.). The goal was to create **a simple and light web app that look like a native application**. For views? Portions of HTML. For transitions between views? CSS transitions. Supporting the “back” button of Android devices as a native application? I played with the hash (onhashchange event).

In short, the web is wide and worldly enough to do pretty much everything you want with…

So I implemented the Same Game on Android. But (naturally) the game already existed on Android! I had to find something new! I was itching to fully exploit the possibilities of a new technology. Mobile has great potential – so it would be bad not to make use of new APIs. I discovered **the Accelerometer**. My idea was gravity: change the balls position by rotating the device.

But, many of my friends don’t have Android phones!

The Same Game Gravity is now available for iPad, iPhone, Android, Facebook, Chrome Store and desktop browsers. That’s a lot of platforms, with a lot of APIs to learn – and potentially a LOT of work in maintenance. But thankfully I didn’t have to go off learning Objective-C and Java Android, or keep track of arm-fulls of repositories! All the platforms are supported from **a single codebase**: thanks to the power and awesomeness of JavaScript, HTML, and CSS – combined with a nifty tool I developed [WebAppBuilder][4] to easily build each instance.

**I added a cool scoring system that spreads via multiple social networks simultaneously and easily – and now I have a truly cross-platform game!**

### The code

Desktop version source code is available on [Github][5].

#### The HTML

(see [game.html][6])

The HTML code is pretty simple.  
Basically, there is a **container which contains different**. Each section is a view of the game.

For instance here is the game view :

```html
<section id="game">
  <div class="turnleft"></div>
  <div class="turnright"></div>
  <div class="gameStatus">
    <a class="i18n-back back" href="#!/">Back</a>
    <span class="timeline">
      <span class="remainingSeconds"
        ><span class="remainingSecondsTime"></span> s</span
      >
    </span>
  </div>
  <div id="gameContainer">
    <canvas class="highlight" width="400" height="300"></canvas>
    <canvas class="main" width="400" height="300"></canvas>
  </div>
</section>
```

In the desktop version, **game.html** is wrapped into **index.html** in an iframe to keep the game independent of the context.

#### The CSS

(see [game.css][7])

CSS 3 is very rich.

CSS Transitions and CSS Transforms has been used to do view change.

```css
/* Pre conditions :
 * With Javascript: 
   - A class "current" is setted for the current section view. 
   - All section after "current" must take a "after" class. 
 */
#main.enabletransition > section {
  /* #main must take "enabletransition" after the DOM load to avoid a first transition */
  transition-duration: 1s, 0s; /* transform takes 1s duration, opacity doesn't have transition */
}
#main > section {
  z-index: -1;
  opacity: 0;
  transition-delay: 0s, 1s; /* opacity go to 0 in 1s */
  transition-property: transform, opacity;
  transform: translateY(-100%); /* go above the page */
}
#main > section.current {
  z-index: 0;
  opacity: 1;
  transition-delay: 0s, 0s;
  transition-transform: translateY(0%); /* go to the bottom */
}
#main > section.after {
  /* same as "#main > section.current ~ section" but without bugs */
  opacity: 0;
  transition-delay: 0s, 1s;
  transform: translateY(100%); /* go below the page */
}

/* Note that this is a part of the css code 
 * (you need to add -webkit-, -moz-, ... in some properties)
 */
```

#### The game core

(see [game.js][8])

Code is organized in different javascript “classes”.

The main components are :

- [game.Grid][9] contains all the algorithm of the game.
- [game.GameCanvasRenderer][10] is a game renderer (graphic part of the game) based on HTML Canvas element. It contains different functions called by **game.Game**.
- [game.Game][11] contains all the game logic, the game loop and bind DOM events (touch, click, …).

#### game.desktop.js: a game instance for the desktop

(see [game.desktop.js][12])

This file contains all the specific code for the desktop version (it overrides existing classes). But it mainly contains the [game controller][13] handling different views and using all game classes.

##### Some significant code

```javascript
// Colors.get(nb) : pick nb random colors
var Colors = (function () {
  var clrs = [
    new Color("#D34040"),
    new Color("#82D340"),
    new Color("#40C2D3"),
    new Color("#8B40D3"),
    new Color("#D3C840"),
  ];
  return {
    get: function (nb) {
      return clrs
        .sort(function () {
          return Math.random() - 0.5;
        })
        .slice(0, nb);
    },
  };
})();

/** Game instanciation **/

var gridSizeByDifficulty = [
  // Size of grid for each difficulty
  { w: 8, h: 8 },
  { w: 12, h: 12 },
  { w: 16, h: 16 },
];
var colorNumberByDifficulty = [3, 4, 5]; // Nb of colors for each difficulty

var difficulty; // can be 0 (easy), 1 (normal) or 2 (hard)
currentGame = new game.Game({
  gridSize: gridSizeByDifficulty[difficulty],
  colors: (colors = Colors.get(colorNumberByDifficulty[difficulty])),
  container: "#game", // container selector
  rendererClass: "GameCanvasRenderer", // The class to use for rendering the game
  difficulty: difficulty,
  drawHover: true,
  globalTimer: new Timer().pause(),
  keepSquare: true, // Keep a square ratio
});
```

### The gravity

The game gravity was maybe the hardest part of the game development.

#### Using device Accelerometer for mobile/tablet version

I needed to find ways to access to the device accelerometer. For Android I used [PhoneGap Accelerometer][14]. But on iPhone I wasn’t able to get PhoneGap’s accelerometer.getCurrentAcceleration to work properly, so I used DeviceMotion event supported by iOS 4.2 . (see [DeviceOrientation spec][15]).

(A big thanks to [@42loops][16] for that: [devicemotionevent.html][17])

![Device orientation schema][18]

#### CSS Transforms and Transitions for the desktop version

Computers don’t have an Accelerometer. _Except maybe some macbook but I’m not sure people would like to turn macbook in 360°!_ but the gravity concept is crucial to the game. I ended up implementing “gravity” via the arrow keys.  
The game is entirely rotated with [CSS Transforms][19] and animated with [CSS Transitions][20].

### The score system

I’ve written a web service with [Play! framework][21] to receive scores or retrieve them from Twitter, validate them and spread them with a json API and widgets.

![tweet example][22]

**This web service will be available soon for game developers.**

The power of this web service is the usage of **social networks**. It will retrieve peoples names, avatars, and their social links without needing to prompt the user.  
For game developers, social scores sharing is a nice way of **advertising your game**: someone shares his scores to his friends: so your game can spread virally.

See that little hash “$4f005″? That’s a way to check if sent scores are valid.  
In fact the web service allows you to handle your own security, via your own “twitter to scores” transformer. You can add a small Javascript function that is executed by the server when transforming a twit to scores – to ensure there hasn’t been any cheating.

The web service also provides **generic widgets** to easily embed game scores in websites.  
If a player has played a few different games using this web scores service, we can provide a “transversal” widget contains all scores of a player.

#### The Same Game Gravity Widget

Same Game Gravity use its own widget ([source code here][23]).

This widget is very customizable. Here’s an example of the code used to embed the widget anywhere (like in this blog post) :

```html
<script
  type="text/javascript"
  src="http://same.greweb.fr/public/javascripts/same.scores.js"
></script>
<script type="text/javascript">
  new same.Scores({
    width: "250px",
    height: "400px",
    items: 3,
    period: "all",
    platform: ["web", "mobile", "tablet"],
    type: ["hs_hard", "hs_normal", "hs_easy"],
    title: "Best highscores ever",
    theme: {
      bg: "rgb(218, 236, 244)",
      color: "#000",
      scores_bg: "rgba(255, 255, 255, 0.5)",
      scores_color: "rgba(0, 0, 0, 0.8)",
      link: "#1F98C7",
    },
  })
    .init()
    .fetch();
</script>
```

### Conclusion

And here we are! 6 months to develop a game and release it on different platforms! I learn a lot about mobile development and I’m now more capable to develop other games.  
I learned that you should avoid using Canvas if you can use DOM instead because performance are bad on some mobile device whereas CSS Transitions / Animations are hardware accelerated.

Finally, I learned that game development is not only about programming! The marketing and the graphical parts are so important too.

Want to checkout the code or contribute to the game i18n? Just fork the [game repository][5].

#### Thanks

Big thanks to all game testers. Friends and colleagues, thank you very much!  
Special thanks to @mrspeaker for English help !

The Same Game is available for 6 different platforms. And I can pump out new builds for them all in around 15 minutes. Here’s how…

Same Game Gravity: 6 platforms, 1 codebase

[1]: /2011/07/same-game-gravity-for-ipad-iphone-android-facebook-chrome-and-web/
[4]: http://gre.github.io/same-game-gravity
[5]: http://itunes.apple.com/us/app/same-game-gravity-for-ipad/id446790701
[6]: http://itunes.apple.com/us/app/same-game-gravity/id445606743
[7]: http://market.android.com/details?id=fr.gaetanrenaudeau.samegame.free
[8]: http://gre.github.io/same-game-gravity
[9]: http://apps.facebook.com/samegamegravity/
[10]: https://chrome.google.com/webstore/detail/eibjpmiiheipmgfhffjpdmojoagccijb

see also [Same Game Gravity Technical Notes][1].

# [Click to play][4]

![](/images/2011/07/promo.png)

[Same Game Gravity][4] is today available on **[iPad][5], [iPhone][6], [Android][7], [Web][8], [Facebook Apps][9] and [Chrome Web Store][10]**.

![](/images/2011/07/same_platform.png)

> Un principe simple remis au goût du jour. Trés bon!! _(bobylito)_

> Great twist (excuse the pun) on the “same” game! _(mrspeaker)_

> A fresh spin on Same Game the use of gravity is pretty clever. _(erwan)_

Same Game Gravity is a mind-bending ball removal puzzle game where you try to remove all of the balls from the board. Balls can only be removed when they are grouped with more balls of the same color. The balls are influenced by gravity. On mobile, you change gravity by rotating your mobile, on desktop you have arrows.



## The game gravity

Rotate your device to apply gravity and change balls arrangement!

![gravity example](/images/2011/07/gravity_exemple.png)

### A pioneering scores system based on social networks

Players share their scores through **Twitter** or directly **from the game** (for the Facebook version). The **user name** and the **avatar** are directly taken from these social networks.
You can easily compare your scores and contact other players with social networks!

Same Game Gravity is today available on iPad, iPhone, Android, Web, Facebook Apps and Chrome Web Store.

Same Game Gravity for iPad, iPhone, Android, Facebook, Chrome, and Web!

[1]: /2011/06/automating-web-app-development-for-multiple-platforms/#webappbuilder
[2]: http://gre.github.io/same-game-gravity
[3]: https://github.com/gre/WebAppBuilder
[4]: http://diveintohtml5.org/
[6]: http://www.phonegap.com/
[8]: http://mustache.github.com/
[9]: http://sass-lang.com
[10]: http://compass-style.org
[12]: http://mrspeaker.net/
[13]: https://github.com/jquery/jquery/tree/master/build

In this article, we will explain why we’d choose web technologies to make applications and introduce [**WebAppBuilder**][1], a tool to easily build different instances of an application. We’ll examine the [Same Game Gravity][2] as an example.

Using web to develop mobile applications is very **productive** and web technologies are **rich**.

[Fork WebAppBuilder on Github.][3]



## Rich?

New web technologies have become rich with CSS3, HTML5 and new Javascript APIs are now being supported on most of smartphones. CSS3 animations, Web Service usage, local storage, Geolocation, drawing shapes (Canvas),.. are some example of new web features.

I won’t expand more on this topic but invite you to [visit this link][4] for more details.

## Productive?

Compared to a native application, the web application **paradigm is reversed**.  
The Web provide a common way to make applications.  
To develop a native application, you must adapt yourself for each device, each new API, or each new language,… but with Web, the device fits to you by proving bridges (accessible via JavaScript) to access device features!  
I mean, you don’t need to dive into the Java Android API or Objective-C language (for iPhone/iPad), or any other API for other devices… You just have to learn **web technologies**.

We are in 2011, the “only desktop application” model is over now, and mobile and tablet are two new platforms you should be aware of. So it changes everything about the technology to use.

### Having a common language for all instances

Instances of a single application can be numerous.  
In fact, an application can be projected in at least 3 axis of instance : The **platform** (mobile, tablet, desktop, …), the **Operating System** (Android, iPhone, webOS) and the **application version** (free version, full version, …).

![](/images/2011/application-axis3.png)

That’s pretty expensive to develop X instances of an application. This is a problem for developing the first version and mainly for maintainability : You want to fix bugs and add features once, and only once.

**So, the point is we need a common language to describe an application with multiple instances.**

### Web is great for that!

Computers have browsers, mobiles and tablets device have recent browsers.

To make your application development fully independent from the device, firstly you need a great **framework** to bridge your application and the device (like [PhoneGap][6]), secondly you need a great tool to easily **build** all applications from your common source code.

First of all, let’s see how to organize a web project.

### Good practice

This is how I’ve organize my project :

#### The source code directory

This directory contains all your web app source code. You should keep your application source code (with HTML, CSS, Javascripts, images, sounds, …) in one directory (like _/src_ ).  
You should **avoid specific code**, but sometimes you still need some specific behaviors for different devices. If so, I recommend you to put these differences inside different files (for exemple: _mobile.html_, _tablet.html_, _computer.html_,…).

#### Project skeletons

Keep one skeleton directory for each instance of your application.  
A skeleton directory will contains all the specific code related to the platform/device/version.  
**Frameworks like PhoneGap bring you these skeletons.**

---

## WebAppBuilder

![](/images/2011/webappmaker.png)

I created **WebAppBuilder : a lightweight Makefile to build your project**. This is a mashup of existing cool stuff like : a small template system (Mustache), SASS with Compass, Javascript minimizer, …

### Features of WebAppBuilder

- Template easily your HTML files with [Mustache][8].
- Copy, concatenate, minimize Javascripts however you want.
- Retrieve Javascript files from URLs (useful for libraries).
- Compile SASS files into CSS files (if you use [this awesome stylesheets language][9])
- Support [Compass][10] if installed (you don’t need to provide it in your source, only an import works)
- Merge your CSS files.
- Copy and optionally rename resources you want to include (images, fonts, sounds,…).
- Error handling and atomicity : if one operation fail, the make fail (javascript syntax error, sass syntax error, …)

You must have one Makefile per project skeleton, so you can easily define what to do with the _/src_ for the related platform/device/OS.

### Download or Contribute

[Fork me on Github][3]

### Example with my Same Game Gravity game

I developed these tools during the [Same Game Gravity][2] game development.

A **make** inside my android/ skeleton gives me :

![](/images/2011/webappmaker-term.png)

And here is the Makefile I use :

#### Android Makefile

```makefile
# Same Game Gravity - Android full version #

        ###             ~ Web App Builder ~               ###
        #       a Makefile to compile a web project.        #
        #  designed for web project with different devices  #
        #  (mobile, tablet, desktop) but with common code.  #
        ###        by @greweb  -  http://greweb.fr/       ###

# BUILD_DIR : PATH to Web App Builder /build directory (the directory containing all build tools)
BUILD_DIR = ../build

# SRC_DIR : the source directory
SRC_DIR = ../app

# DIST_DIR : the dist directory (ex: assets for android, www for iphone)
DIST_DIR = assets

# RESOURCES : Your assets (images, sounds, fonts... and other static files)
# You can rename dist file by prefix newname= ( ex: index.html=iphone_version.html )
RESOURCES = Chewy.ttf logo.png background.jpg pop.mp3 swosh.mp3 gravity_exemple.png

# VIEWS : Views will be interpreted by Mustache.js
# You can pass arguments with JSON format.
# Example: index.html:"{key1:value1,key2:value2,...}"  <= no spaces!
VIEWS = index.html=mobile.html:"{versionType:'',version:'1.0',platform:'mobile',android:true,free:false}"

### SCRIPTS : all javascripts
# - You can pass an URL to retrieve
# - if you want to minimize the JS, prefix with '!'
# - to mix scripts, concat them with a comma ','
# - to set the destination name, you can prefix scripts with 'myname.js=' else the first script name is used ( exemple: all.js=util.js,ui.js,main.js ).
SCRIPTS = game.min.js=!game.js,!game.mobile.js,!md5.js \
          phonegap.min.js=!phonegap.js,!phonegap.webintent.js \
          jquery.min.js=http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js,jquery.ba-hashchange.min.js,jquery.tmpl.min.js

### STYLES : all styles : CSS or SASS
# - For .sass files, we compile them to css
# - Like before, you can mix styles with ',' and you can name your target by prefixing 'name='
STYLES = game.css=mobile.sass

########################################################################


all: welcome clean assets_views assets_scripts assets_styles assets_files

welcome:
	@@${BUILD_DIR}/welcome.sh

assets_base:
	@@mkdir -p ${DIST_DIR}

assets_views: assets_base
	@@${BUILD_DIR}/compile_views.sh ${SRC_DIR} ${DIST_DIR} ${VIEWS}

assets_scripts: assets_base
	@@${BUILD_DIR}/compile_scripts.sh ${SRC_DIR} ${DIST_DIR} ${SCRIPTS}

assets_styles: assets_base
	@@${BUILD_DIR}/compile_styles.sh ${SRC_DIR} ${DIST_DIR} ${STYLES}

assets_files: assets_base
	@@${BUILD_DIR}/copy_resources.sh ${SRC_DIR} ${DIST_DIR} ${RESOURCES}

clean:
	@@rm -rf ${DIST_DIR}

.PHONY: welcome clean assets_views assets_scripts assets_styles assets_files
```

### Configuring your IDE

I use mainly komodo and geany as an IDE. They both have a build system. I recommand you to configure your IDE to make && open the page just by pressing a shortcut key.

### Features planned

- make should build the .apk for Android app

## Special thanks

- to [mrspeaker][12] for English review.
- to [jQuery build system][13] (js minifier)

In this article, we will explain why we’d choose web technologies to make applications and introduce WebAppBuilder, a tool to easily build different instances of an application. We’ll examine the Same Game Gravity as an example.

Automating Web App development for multiple platforms


#

Following on from the success of my Same game made in HTML5 Canvas, I’ve decided to extend it to a (web) mobile game.

It’s now available on Android market.

More infos on <http://gre.github.io/same-game-gravity>.

<iframe width="640" height="360" src="http://www.youtube.com/embed/Qyd69g9hmIY?feature=player_embedded" frameborder="0" allowfullscreen></iframe>

This ball removal puzzle game is made with HTML5 technologies and PhoneGap. Source code will be published within a few months.


Following on from the success of my Same game made in HTML5 Canvas, I’ve decided to extend it to a (web) mobile game.

Releasing Same Game Gravity (Android)

[1]: http://whatwg.org/html
[2]: http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html
[3]: http://www.mrspeaker.net/dev/parcycle/
[4]: http://en.inforapid.org/
[5]: http://gre.github.io/same-game-gravity
[6]: http://fizz.bloom.io/
[7]: http://easeljs.com/
[8]: http://processingjs.org/

Cette vidéo de 20 minutes présente les possibilités du Canvas à travers quelques démos et l’implémentation pas à pas d’un exemple basique.  
Elle est destinée à des développeurs débutant dans l’utilisation de Canvas.

<iframe src="http://player.vimeo.com/video/20957255?portrait=0" width="550" height="410" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

_Dans la suite de l’article : les liens et codes de la vidéo …_



## Liens

### Specs

- [whatwg.org/html][1]
- [Canvas][2]

### Exemples

- [parcycle][3]
- [Visualisation des relations entre sujets (wikipédia)][4]
- [Same Game][5]
- [fizz : visualisation des tweets][6]

### Bibliothèques graphiques

- [EaselJS][7]
- [Processing JS][8]

## Exemple de l’implémentation

```html
<html>
  <head>
    <style>
      body {
        background: #ddd;
      }
      canvas {
        background: #fff;
      }
    </style>
  </head>
  <body>
    <canvas id="sketch" width="300" height="300"></canvas>
    <img
      id="image"
      src="http://www.whatwg.org/images/logo"
      style="display: none;"
    />

    <script type="text/javascript">
      (function () {
        var canvas = document.getElementById("sketch");
        var ctx = canvas.getContext("2d");
        var img = document.getElementById("image");

        var i = 0;
        setInterval(function () {
          ctx.clearRect(0, 0, 300, 300);

          ctx.drawImage(img, 0, 0, 300, 300);

          ctx.fillStyle =
            "rgba(255, 0, " + Math.floor(Math.sin(i / 50) * 255) + ", 0.8)";
          ctx.fillRect(100, i % 300, 100, 100);

          /*
        
        ctx.strokeStyle = '#09F';
        ctx.lineWidth = 5;
        
        ctx.beginPath();               // commence à tracer un chemin
        ctx.moveTo(0, 20);             // défini le premier point de tracage à la position (0, 20)
        ctx.lineTo(canvas.width-100, 30);  // Tracer une ligne jusqu'à la position (canvas.width, 30). canvas.width désigne la largeur du canvas (500 dans notre exemple).
        ctx.bezierCurveTo(100, 200, 0, 100, 300, 300);
        ctx.stroke();                  // Indique au canvas de dessiner le chemin tracé depuis le beginPath
        
        */

          ++i;
        }, 30);
      })();
    </script>
  </body>
</html>
```

Cette vidéo de 20 minutes présente les possibilités du Canvas à travers quelques démos et l’implémentation pas à pas d’un exemple basique.

HTML Canvas pour les néophytes

**[EDIT] Note: the DWA-140 B2 is now supported by recent Linux version.**

I’m using ArchLinux and I finally make my DWA-140 B2 Wifi USB adaptor work !

If you have the same problem, you can read this article to fix it !



**My conf**:

- Linux Kernel: _2.6.36_
- Architecture: _x64_
- Device: _ID 07d1:3c0a D-Link System DWA-140 RangeBooster N Adapter(rev.B2) [Ralink RT2870]_

## What to use ?

So the only way I found to make it work nicely is to use **ndiswrapper**, a Windows XP driver wrapper, and **wpa_supplicant**, a WLAN tool.

First, I’ve tried some RaLink drivers but this was not really great, I’ve succeed to make `ra2870` work only one time but there was some lags each 20 seconds (like 1000ms ping frequently).

Moreover, I recommend not using NetworkManager with this method, it seems ndiswrapper and networkmanager produced awful results for this bundle (like waiting 30s for wifi to connect (or not connecting!), or freezing my Linux, …). Use wpa_supplicant utils like netcfg instead of !

## Procedure

Alternatives rejected, here is the solution step by step :

### Pre-conditions

With a wired connection, install these packages (with your package manager) : **ndiswrapper**, **wpa_supplicant** and (optional) **netcfg**.

Unfortunately, I had some freeze issues with the current ndiswrapper repository version so I checkout ndiswrapper SVN source code on and recompile it. **Maybe you have to do the same.**

1.  Don’t plug your bundle yet. Insert the CD of the product. It contains the driver we need for ndiswrapper. You need to find the `/Drivers/WinXPx64/` (it may depend on your arch) **.inf** file. You can also download the last driver on the [D-Link website][2].
2.  Go on commandline in root mode and type:

```bash
ndiswrapper -i {path of the .inf file}
```

Example:

```bash
ndiswrapper -i /media/cdrom0/Drivers/WinXPx64/Drt2870.inf
```

- Plug your bundle and check if the command `ndiswrapper -l` say something like:

```
drt2870 : driver installed
device (07D1:3C0A) present
```

If not you maybe need to `ndiswrapper -r drt2870` to remove the driver and return to the second step trying another `/Drivers/*/*.inf` file.

- Next, you need to configure your `wpa_supplicant.conf` configuration file for your wifi access point. Refer to the [documentation][3].
- Try to run `wpa_supplicant` :

```bash
wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf
```

Once this working, you maybe need to run dhcpd :

```bash
dhcpd wlan0
```

- Now you can try your internet connection, by pinging google.com or try to browse the web.
- If it works, you can save your configuration, refer to the [documentation][3].

**For any problem, feel free to comment this article.**

[2]: http://www.dlink.com/products/?tab=3&pid=DWA-140&rev=DWA-140_revB
[3]: https://wiki.archlinux.org/index.php/WPA_supplicant

How to make DLink DWA-140 B2 perfectly work on Linux

[1]: http://www.w3.org/TR/css3-transitions/

[CSS3 transitions][1] are now available on Firefox, Chrome, Safari, Opera and … IE9!, and it’s awesome.

> CSS Transitions allows property changes in CSS values to occur smoothly over a specified duration.

**Javascript is not anymore required for simple animation.**

Specifically, we don’t need Javascript to manage animation with **setInterval** or with any library like **jQuery.animate** : Forget the animation management, stay focused on the real work.

In this article, I will try to explain why and how using css3-transition with some examples.



## Why ?

- It’s **simple** and **smart** : adding one line of css code.
- It **let the browser rendering animation instead of using javascript complex code**. You don’t have to worry about animation and performance. So you can stay focused on real part of your project.
- It’s **cleaner** than some javascript animation implementation because you don’t modify style attribute during animations. So, it’s also probably more efficient.
- **Degradation is great.** If your browser doesn’t support CSS Transition, it’s not really bad, only the animation is not available. **Other behaviors aren’t alterate**. For example, imagine a photo slide-show with zoom effect when changing photo. With an old browser, photos are just instantly zoomed without animation. That’s not bad.
- And off course, It’s **standard**.

## How ?

CSS Transition are **extremely simply to use**.

### transition-duration

Basically, you set a **css time properties** in a css selector _like `-moz-transition-duration: 1s;` for mozilla_. This time define the animation duration. Browser will determine the transition between this selector and a descendant selector.

Not that css3 transition is currently in draft mode, so there are multiple property for each browser (the prefix change).

For Firefox (3.7 ), Chrome (and other webkit browser) and Opera, you have to use :

```css
-moz-transition-duration: 1s;
-webkit-transition-duration: 1s;
-o-transition-duration: 1s;
```

Don’t panic, in the future (on CSS3 release), only one property will be used.

#### Example

```css
.box {
  -moz-transition-duration: 1s;
  -webkit-transition-duration: 1s;
  -o-transition-duration: 1s;

  margin: 10px;
  background-color: red;
}
.box:hover {
  margin: 50px;
  background-color: green;
}
```

On mouse over the **.box**, during one second : margin will move from **10px** to **50px** and background-color will move from **red** to **green**. That’s all!

### transition-property

You can also specify the name of the CSS property to which the transition is applied.

For instance, **color**, **width**, **opacity**, …

#### Like this

```css
-moz-transition-property: margin, background-color;
-webkit-transition-property: margin, background-color;
-o-transition-property: margin, background-color;
```

### Others properties

More properties are available to specify more deeply transition effects. Retrieve them on [CSS Transitions Working Draft][1].

- transition-timing-function
- transition-delay

## Examples

Here are some CSS transition examples.

- [A box with color, text, shapes transformation.](/demo/css3/transition/box1/)
- [Letters animation.](/demo/css3/transition/letters/)
- [Image slider.](http://sliderjs.org/)
- [Navigation bar.](/demo/css3/transition/navbar/)

CSS3 Transitions


Il est préférable d’**utiliser un framework web** même si l’on veut réaliser un **site vitrine simple (statique)**, car l’on bénéficie des avantages du framework notamment de l’héritage (entre autre) des templates, de l’internationalisation, de la configuration des _routes_, du _SASS_, etc.

De plus, cela permet de rendre la maintenabilité moins longue et couteuse.

Néanmoins, son hébergeur ne permet pas toujours de faire tourner son site avec le framework utilisé (par exemple _ruby on rails_ ou _play! framework_).

Pour remédier à ce problème, il suffit d’**exporter son site statique en simples pages HTML**.

Cet article est donc destiné aux particuliers ne voulant pas investir dans un serveur dédié, fans de framework avancés qui ne sont pas supportés par les offres d’entrée de gamme des hébergeurs (qui n’offrent généralement que le support du php).

**D’ailleurs, pour ce type de site, pourquoi utiliser un framework MVC si l’on utilise que des vues ?**

## La démarche

### Le site web

**Réalisez le site** avec votre framework préféré et faites en sorte que la page principale (**/**) **permette l’accès à toutes les pages du site** par des liens (pas forcément directs).

### Exportation

Avec **wget** récupérez votre site à la ligne de commande :

```bash
wget -r -k -np "http://localhost:9000/"
```

A l’instar d’un moteur de recherche, c’est cette commande qui va s’occuper de **retracer toutes les pages web de votre site**, mais aussi toutes ses ressources (images, css, js, ..). En plus de cela, elle va **préserver le fonctionnement des liens** entre pages.

Adaptez _http://localhost:9000/_ à l’url de votre site.

Cela va créer le dossier _localhost:9000_, il ne vous restera plus qu’à l’envoyer sur votre serveur http.

## Internationalisation

Voici une solution pour exporter son internationalisation.

Elle consiste à rediriger l’utilisateur, depuis la page principale, sur la bonne page internationalisée en fonction de sa langue (indiquée par le navigateur), tout **en gardant les fichiers publics en commun** (css, images).

### Préparer ses routes

préparez les uri pour qu’elles soient de la forme **/{lang}/\*/** avec **lang** désignant la langue désirée.

#### Exemples de routes

```
/en/
/en/about/
/fr/
/fr/about/
```

### Ajouter des liens dans les templates pour changer de langue

Cette action est délicate car, comme précisé auparavant, **wget** essaye de retracer tous les liens entre pages.

Ainsi, si l’on crée des liens entre les différentes langues, **wget** créera un dossier _public_ pour chaque langue internationalisée.

Pour contourner ce problème et ainsi factoriser les fichiers communs, **une solution est de créer les liens à posteriori**.

#### Solution exemple avec play framework

```
<p>
#{if lang!='en'}
  <a ADD_HERE_ENGLISH_LINK_ATTRIBUTES>english version</a>
#{/if}
#{if lang!='fr'}
  <a ADD_HERE_FRENCH_LINK_ATTRIBUTES>french version</a>
#{/if}
</p>
```

```bash
#!/bin/bash
# script bash
wget -r -k -np "http://localhost:9000/"
sed -i s/ADD_HERE_ENGLISH_LINK_ATTRIBUTES/href=\"\\/en\\/\"/g $(find . -name "*.html")
sed -i s/ADD_HERE_FRENCH_LINK_ATTRIBUTES/href=\"\\/fr\\/\"/g $(find . -name "*.html")
```

### Préparer une page de redirection

**Placez à posteriori un script de redirection à l’url /** pour rediriger vers la page adéquat.

#### Par exemple un script php

```php
<?php
$langs = array();

if (isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) {
    preg_match_all('/([a-z]{1,8}(-[a-z]{1,8})?)\s*(;\s*q\s*=\s*(1|0\.[0-9]+))?/i', $_SERVER['HTTP_ACCEPT_LANGUAGE'], $lang_parse);
    if (count($lang_parse[1])) {
        $langs = array_combine($lang_parse[1], $lang_parse[4]);
        foreach ($langs as $lang => $val) {
            if ($val === '') $langs[$lang] = 1;
        }
        arsort($langs, SORT_NUMERIC);
    }
}

foreach ($langs as $lang => $val) {
  if (strpos($lang, 'fr') === 0) {
    header('Location: fr');
    die();
  }
  else if (strpos($lang, 'en') === 0) {
    header('Location: en');
    die();
  }
}
header('Location: en');
?>
```


Automatiser l'exportation d'un site statique avec wget

[1]: http://compass-style.org/
[2]: /2010/03/sass-levolution-du-css
[3]: /images/2010/css3/exemple_border_radius.png
[4]: /images/2010/css3/exemple_gradient.png
[5]: /images/2010/css3/exemple_text_shadow.png
[6]: /images/2010/css3/exemple_box_shadow.png
[7]: /images/2010/css3/university_nostalgia_exemple.png
[8]: http://github.com/gre/University-nostalgia
[9]: /images/2010/css3/triangle_01.png
[10]: /images/2010/css3/triangle_02.png
[11]: /images/2010/css3/triangle_03.png
[12]: /images/2010/css3/triangle_menus.png

Le CSS depuis sa version 3 constitue une **bonne évolution technologique pour palier l’utilisation abusive d’images** dans la réalisation d’une application web.

Il n’est ainsi plus nécessaire de recourir à des images pour réaliser des **ombres**, des **dégradés**, des **bordures arrondis** ou encore utiliser des **polices spécifiques**.

L’avenir du CSS3 nous promet encore plus : il est d’ores et déjà possible sur certains navigateurs d’effectuer des **animations**, des **transitions**, des **effets de reflets**,… sans devoir recourir au _javascript_, au _canvas_ ou, pire encore, au _flash_.



## Généralités

### Pourquoi ?

Quelques raisons pour utiliser le CSS 3…

#### dans une optique de maintenabilité

En utilisant des images pour réaliser des effets simples, **il faut mettre à jour l’image à chaque fois**. Si bien qu’il est nécessaire d’utiliser un logiciel de dessin et de garder les sources pour pouvoir facilement modifier les couleurs à l’avenir.  
**La modification d’un thème est alors pénible** : Pour chaque image du thème : il faut ouvrir la source de l’image avec son logiciel préféré (GIMP, Photoshop, …), modifier la couleur, exporter l’image, recharger la page,… A contrario, **il ne suffit que de modifier une ligne de code CSS pour changer sa couleur** (l’utilisation de variable avec SASS est intéréssant).

#### par simplicité

Le CSS 3 **offre plus de possibilités** donc **simplifie bien des tâches** qui étaient complexe à réaliser auparavant. Bordures arrondis, ombres, dégradés, animations, reflets,… sont maintenant facilement réalisables avec le CSS 3.

Voici un exemple frappant parmi tant d’autres :  
Auparavant, on voyait fleurir à foison des tableaux pour réaliser de simples bordures arrondis.

##### On voyait auparavant

```html
<table class="radius">
  <tr>
    <td class="topleft"></td>
    <td class="top"></td>
    <td class="topright"></td>
  </tr>
  <tr>
    <td class="left"></td>
    <td class="content">content here...</td>
    <td class="right"></td>
  </tr>
  <tr>
    <td class="bottomleft"></td>
    <td class="bottom"></td>
    <td class="bottomright"></td>
  </tr>
</table>
<style>
  table.radius .topleft {
    background: url(topleft.png);
    width: 20px;
    height: 20px;
  }
  /* DE MEME pour les 8 autres cases ... */
</style>
```

##### Maintenant avec le CSS3

```html
<div class="radius">content here...</div>
<style>
  .radius {
    border-radius: 20px;
  }
</style>
```

#### dans un objectif de scalabilité des thèmes

L’utilisation des possibilités du CSS 3 au lieu d’images va permettre d’**étendre rapidement son application web à plusieurs thèmes** et de modifier facilement ces thèmes. Il suffira d’avoir un fichier pour chaque thème.

### SASS et le framework Compass

Afin de résoudre les problèmes de _cross-navigateur_ abordés précédemment, je vous conseille l’utilisation du **SASS** et du framework [Compass][1].  
Pour plus de renseignements sur le SASS, n’hésitez pas à lire [cet article][2].

### Principales nouveautés du CSS 3

Dans la suite de cet article, **pour plus de simplicités, nous nous arrêtons à la compatibilité de Firefox** (préfixé par -moz) mais bien entendu, il est possible de les rendre compatibles avec tous les navigateurs récents. Comme précisé avant, l’utilisation du framework _Compass_ permet entre autres de résoudre ce problème.

#### Les bordures arrondis

![][3]

```css
.exemple {
  -moz-border-radius: 10px;
  border: 1px solid black;
  padding: 2px 5px;
}
```

#### Les dégradés

Compatibles depuis Firefox 3.6.  
![][4]

```css
.exemple {
  -moz-border-radius: 10px;
  border: 1px solid black;
  padding: 2px 5px;
  background: -moz-linear-gradient(-90deg, green, yellow);
}
```

#### Les ombres

##### Sous les textes

![][5]

```css
.exemple {
  -moz-border-radius: 10px;
  border: 1px solid black;
  padding: 2px 5px;
  background: -moz-linear-gradient(-90deg, green, yellow);
  text-shadow: -1px -1px 1px yellow;
}
```

##### Sous les éléments

![][6]

```css
.exemple {
  -moz-border-radius: 10px;
  border: 1px solid black;
  padding: 2px 5px;
  background: -moz-linear-gradient(-90deg, green, yellow);
  text-shadow: -1px -1px 1px yellow;
  -moz-box-shadow: 1px 1px 1px rgba(0, 0, 0, 0.5);
}
```

A noter d’ailleurs que la couleur de format **rgba(r, g, b, a)** est une nouveauté du CSS 3.

### Optimiser la compatibilité avec les navigateurs plus anciens

Voici une utilisation intelligente des dégradés (avec SASS) pour permettre une meilleure **compatibilité** avec, en dernier recours, une couleur ou une image alternative :

```sass
=vertical-gradient(!from, !to, !alt=(!from/2   !to/2))
  background = !alt
  background = -webkit-gradient(linear, left top, left bottom, from(!from), to(!to))
  background = -moz-linear-gradient(-90deg, !from, !to)

/* exemples d'utilisation : */
#main > header
   vertical-gradient(#719369, #587451, url(header.png))

#main > header
   vertical-gradient(green, yellow, #80FF80)
```

## Exemple de maquette

Voici un **exemple d’utilisation du CSS3** utilisé sur un projet récent (réalisé à l’université).

![][7]

Il n’y a aucune image (sauf l’avatar tux) et l’application est entièrement compatible avec au minimum Firefox et Chrome.  
Si l’application vous intéresse, elle est sur [github][8].

### Extrait du code SASS

```sass
@import compass.sass
@import compass/reset.sass
@import theme.sass

=vertical-gradient(!from, !to, !alt=(!from/2   !to/2))
  background = !alt
  background = -webkit-gradient(linear, left top, left bottom, from(!from), to(!to))
  background = -moz-linear-gradient(-90deg, !from, !to)

!back = #e9f3e7
!back_aside = #F8FAF5
!back\_header\_from=#719369
!back\_header\_to=#587451
!back\_footer\_from=#b4c1b1
!back\_footer\_to=#9da89a

#wrapper
   border-radius(!global\_border\_radius)
  :border 1px solid !back-#111
  >nav
     border-top-radius(10px)
    :background white
  >header
     vertical-gradient(!back\_header\_from, !back\_header\_to, url(/public/images/header.png))
    :color white
    :z-index 1
  >footer
     vertical-gradient(!back\_footer\_from, !back\_footer\_to)
     border-bottom-radius(10px)

  #main
    background = !back_aside
     box-shadow(0px, -1px, 2px, rgba(,,,0.25))
    :z-index 2
    >section
      :background white
```

### Un triangle en css ???

Ce n’est pas de la magie mais **il est possible de faire des triangles en CSS** (même en CSS2) grâce à une petite astuce. Explication en images :

#### Une boite avec une couleur pour chaque bordure

![][9]

```css
.box {
  background: black;
  width: 40px;
  height: 40px;
  border-width: 15px;
  border-color: yellow red blue green;
  border-style: solid;
}
```

#### width et height à 0

![][10]

#### Bordures transparentes

![][11]

```css
.box {
  background: black;
  width: 0;
  height: 0;
  border-width: 15px;
  border-color: transparent red transparent transparent;
  border-style: solid;
}
```

#### Autre utilisation des triangles

Le même procédé m’a permis de faire ceci :  
![][12]

Réaliser une maquette web avec le CSS 3

[1]: http://sass-lang.com/
[2]: http://www.playframework.org/
[3]: http://compass-style.org/
[4]: http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html

**SASS, Syntactically Awesome Stylesheets**, est un langage de feuille de style évolué qui permet de factoriser beaucoup de code css et de rendre son écriture et sa maintenance **rapide et moins contraignante**. Il est compilé en css.



## Pourquoi utiliser SASS ?

Son utilisation a de nombreux avantages par rapport au CSS :

- sa **simplicité** (pas de crochets, pas de point virgule mais juste de l’indentation)
- l’**imbrication** des sélecteurs css (appliquant l’idée DRY : don’t repeat yourself)
- l’utilisation de **variables**
- l’utilisation d’**opérations élémentaires** (sur les pixels, les couleurs, …)
- la **factorisation** du code (au lieu de faire des copier-coller, on peux factoriser le code à travers les “mixins”).
- La **réduction** css et la **clarté** du code
- La **compression du code** compilé avec la possibilité de tout mettre dans un fichier (via l’héritage) et de minimifier le code css.

Ce langage n’est pas difficile à apprendre, cela ressemble au css, avec de nombreuses fonctionnalités intéressantes en plus.

## La syntaxe du langage

La syntaxe du sass est **compatible avec celle du css à quelques exceptions près** :

- Ne plus mettre de point virgule **;**
- Ne plus mettre de crochets **{ }**
- Respecter les conventions traditionnelles (**attribut: valeur** un espace après le deux points mais pas avant)
- Respecter l’indentation : Il faut choisir une indentation et s’y tenir dans un même fichier. Au choix : une tabulation, 2 espaces, 4 espaces, … Les lignes _propriétés: valeurs_ d’un sélecteur css doivent dépasser d’une indentation ce sélecteur.

En respectant ces points, vous pouvez déjà **coder en SASS comme en CSS**.

Mais cela ne serait pas intéressant sans les nouveautés suivantes :

### La factorisation des sélecteurs en plusieurs niveaux

Au lieu d’avoir ce type d’arborescence à un niveau :

```sass
.main .head
  color: red
.main .body
  color: blue
```

Nous pouvons factoriser le sélecteur “_.main_” et se ramener à deux niveaux :

```sass
.main
  .head
    color: red
  .body
    color: blue
```

Ce procédé de factorisation basé sur l’esprit **DRY** (Don’t Repeat Yourself) est aussi applicable sur les attributs eux-mêmes :

```sass
a
  font:
    family: serif
    weight: bold
    size: 1.2em
```

sera compilé en css par :

```css
a {
  font-family: serif;
  font-weight: bold;
  font-size: 1.2em;
}
```

### Les variables

La possibilité d’utiliser des variables est un gros apport au css. Elle permet **une meilleure maintenance du code et une meilleure scalabilité d’une application** (en utilisant par exemple des fichiers sass de thèmes définissant toutes les couleurs, images, polices, …).  
Il existe plusieurs **types de variables** (nombre réel, pixels, couleurs, chaines de caractères …) et il est possible d’utiliser des **opérations élémentaires**.

Lorsqu’on écrit une ligne **attribut / value** avec l’utilisation de variables (dynamique),  
on utilise le caractère ‘**=**‘ au lieu de ‘**:**‘ pour l’affectation.

#### Les couleurs

```sass
!link_color = red
a
  color = !link_color
  &:hover
    color = !link_color #222
```

A noter que le symbole **&** remplace le sélecteur parent.

Ce qui donne le code compilé suivant :

```css
a {
  color: red;
}
a:hover {
  color: #ff2222;
}
```

#### Les pixels

```sass
!margin = 16px
.border
  padding = !margin / 2
  margin = !margin / 2
```

donne le code compilé :

```css
.border {
  padding: 8px;
  margin: 8px;
}
```

### Les “mixins”

Les mixins sont des procédures qui contiennent plusieurs lignes de sass.  
Il est possible d’utiliser des arguments sur ces mixins.

```sass
=border-radius(!radius = 5px)
  border-radius= !radius
  -moz-border-radius= !radius
  -webkit-border-radius= !radius
```

```sass
#wrapper
   border-radius(10px)
  > footer
     border-radius()
```

Cet exemple est typiquement intéressant car il permet d’utiliser **border-radius** de façon **cross-browser** et avec une ligne de code.

A noter qu’il est possible d’affecter des valeurs par défaut aux mixins.

Le résultat css compilé est le suivant :

```css
#wrapper {
  border-radius: 10px;
  -moz-border-radius: 10px;
  -webkit-border-radius: 10px;
}
#wrapper > footer {
  border-radius: 5px;
  -moz-border-radius: 5px;
  -webkit-border-radius: 5px;
}
```

### Exemple complet

Voici un exemple complet de l’utilisation du SASS

```sass
/* This is just an example */

/* variables */
!main_width = 900px
!aside_width = 300px
!section_width = 520px

!link_color = red

!font_title = "Liberation","Georgia","serif"

/* mixins */
=border-radius(!radius = 5px)
  border-radius= !radius
  -moz-border-radius= !radius
  -webkit-border-radius= !radius

=block()
  display: block
  overflow: auto

/* colors */
a
  color = !link_color
  &:hover
    color = !link_color #222


/* layout */

#wrapper
  margin:  auto
  position: relative
  width = !main_width
   border-radius(10px)
  >nav
     block()
    padding: 2px
      top: 5px
    font-size: 1.2em
    font-family = !font_title
    a
      font-weight: bold
      &:hover
        color: white

  >header
     block()
    clear: both
    height: 48px
    font-family = !font_title

  >footer
     block()
    padding: 5px
    text-align: center
    clear: both

  #main
    position: relative
    >section
       block()
      width = !section_width
      padding: 20px

    >aside
       block()
      float: right
      width = !aside_width
      padding: 20px
```

et le résultat du fichier CSS compilé

```css
/* This is just an example */
/* variables */
/* mixins */
/* colors */
a {
  color: red;
}
  a:hover {
    color: #ff2222;
}

/* layout */
#wrapper {
  margin:  auto;
  position: relative;
  width: 900px;
  border-radius: 10px;
  -moz-border-radius: 10px;
  -webkit-border-radius: 10px;
}
  #wrapper >nav {
    display: block;
    overflow: auto;
    padding: 2px;
    padding-top: 5px;
    font-size: 1.2em;
    font-family: Liberation, Georgia, serif;
}
    #wrapper >nav a {
      font-weight: bold;
}
      #wrapper >nav a:hover {
        color: white;
}
  #wrapper >header {
    display: block;
    overflow: auto;
    clear: both;
    height: 48px;
    font-family: Liberation, Georgia, serif;
}
  #wrapper >footer {
    display: block;
    overflow: auto;
    padding: 5px;
    text-align: center;
    clear: both;
}
  #wrapper #main {
    position: relative;
}
    #wrapper #main >section {
      display: block;
      overflow: auto;
      width: 520px;
      padding: 20px;
}
    #wrapper #main >aside {
      display: block;
      overflow: auto;
      float: right;
      width: 300px;
      padding: 20px;
}
```

Le SASS offre **encore plus de possibilités**, notamment l’interpolation, les conditions, les boucles, …  
Vous trouverez plus d’informations sur la _documentation SASS_.

## Utilisation

### Pré-requis

**Note**: Ce qui suit ne s’applique pas pour le plugin sass du framework Play! .

Pour utiliser SASS, sous linux, installez les packets **ruby** et **rubygems** puis installez **haml** avec la commande :

```bash
gem install haml
```

### Avec le framework java Play!

Grâce au module sass de play framework, le SASS est **compilé à la volée** au moment du chargement d’une page (en mode développement) ou au chargement de l’application (en mode production).

#### Installation

Depuis play 1.1, il suffit de lancer la commande

```bash
play install sass
```

Ensuite il faut activer le module dans la configuration de l’application (fichier _conf/application.conf_).

### Avec le framework Ruby on Rails

#### Installation

Pour activer le plugin SASS sur une application Rails, lancez :

```bash
haml --rails path/to/rails/app
```

### Autrement

Vous pouvez toujours utiliser SASS en compilant vos fichier sass en css à chaque modification (voir _Commandes pratiques_).  
Vous inclurez ensuite le fichier css compilé dans votre html.

## Convertir ses anciens CSS en SASS

Si vous ne voulez pas repartir de zéro dans le design d’un projet, vous pouvez tout à fait repartir avec les anciens CSS en les exportant en SASS.

## Commandes pratiques

- Pour convertir vos fichier CSS en SASS il vous suffit d’utiliser : `css2sass`

- Pour compiler vos fichier SASS en CSS, utilisez: `sass`

## Liens

- [Site du langage SASS][1]
- [Site du framework Play!][2]

### Aller plus loin

- [Compass : framework SASS][3]
- [Documentation SASS][4]

SASS : l'évolution du CSS pour Play, Rails ou autres


[2]: http://gre.github.io/same-game
[3]: http://github.com/gre/same-game

I've made a simple canvas game in **HTML5 Canvas**.

**Canvas is a really great API** which allows to do awesome things combined with **javascript** language. It’s a **standard alternative to Flash** and for that kind of usage, I think it can fairly compete Flash.

![screenshot](/images/2010/same_game_screenshot.png)

You can test the game in a **recent browser** _(canvas-compatible like firefox, chrome, …)_ **following [this link][2]**.

If you want to **hack the code**, see the javascript [here][3].

The game was simple to code, except maybe the animation managment which require some **optimization perspective**. The code source is still not perfect, I may improve soon.

## Video demonstration

<iframe src="http://player.vimeo.com/video/9606570" width="500" height="375" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

_Released with the GNU General Public Licence._


The same game in HTML5 canvas

[1]: /2011/03/html-canvas-pour-les-neophytes
[2]: /demo/animate-banner/canvas-cartesian.png
[3]: /demo/animate-banner/step1.html
[4]: /demo/animate-banner/bezier-schema.png
[5]: /demo/animate-banner/step2.html
[6]: /demo/animate-banner/bezier-exemple.png
[7]: http://paulirish.com/2011/requestanimationframe-for-smart-animating/
[8]: /demo/animate-banner/step3.html
[9]: /demo/animate-banner/step4.html
[10]: /demo/animate-banner/step5.html
[11]: /demo/animate-banner/step6.html
[12]: /demo/animate-banner/final.html

![](/images/2010/animated_banner.png)

**Pré-requis conseillé: [Voir la vidéo : HTML Canvas pour les néophytes][1]**

Le **HTML 5** intègre de nouvelles technologies comme le **canvas**, une véritable API graphique destinée à remplacer le flash dans les années à venir.

Ce tutoriel vise à présenter **canvas** comme une **librairie très simple d’utilisation et haut niveau** grâce au langage **javascript**.

Il vous apprendra à réaliser une animation similaire à la bannière <del>actuelle</del> (ancienne maintenant) de mon blog en **quelques lignes de code**.

Il est volontairement ordonnancé de manière didactique, si vous maitriser les concepts, n’hésitez pas à avancer.



## Code de base (skeleton template)

Nous allons travailler avec ce code **html** de base :

```html
<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <canvas
      id="tuto"
      width="500"
      height="100"
      style="border: 1px solid;"
    ></canvas>
    <script language="javascript">
      var canvas = document.getElementById("tuto");
      var ctx = canvas.getContext("2d");

      // Le code javascript ira ici
    </script>
  </body>
</html>
```

Ce code nous servira dans tous le reste du tutoriel.

### Deux choses notables :

- Nous avons créé un élément **canvas** et indiqué ses dimensions **(500×100)**. Pour mieux pouvoir repérer ses dimensions, nous lui avons ajouté une bordure.
- En **javascript**, nous avons récupéré l’élément DOM puis le contexte 2d qui nous servira pas la suite.

## Quelques notions de base du canvas

### La surface du canvas

Le **canvas** occupe une surface dont la dimension est définie par les paramètres _width_ et _height_.

Pour ceux qui ne serait pas familier avec les **bibliothèques graphiques**, cette surface peut être vu comme un quadrillage de pixel sur **deux dimensions** : **x** variant de _0 à width_ et **y** variant de _0 à height_.

Le point d’origine de ce repère orthonormé est situé **dans le coin haut gauche du canvas**:

![][2]

### Le concept de contexte

Le contexte 2d récupéré dans la variable **ctx** est en fait l’**interface de programmation** (API) de la bibliothèque graphique **canvas**.

C’est en quelque sorte l’**intermédiaire entre le programmeur et la bibliothèque graphique**.

Ainsi par exemple, si l’on veux dessiner un rectangle de dimension **20×10** à la position **(5,6)**, il suffit simplement d’écrire:

```javascript
ctx.fillRect(5, 6, 20, 10);
```

### Les paramètres globaux du canvas

Pour dessiner, toute librairie graphique a besoin de connaitre un certain nombre de paramètres tels que la _couleur du trait, la taille de la brosse, etc_.

Plutôt que de devoir passer en paramètre ces informations aux fonctions du contexte, **canvas** met directement à disposition ses paramètres afin de pouvoir les modifier facilement.

Ainsi, nous pourrons définir la couleur de remplissage dans **ctx.fillStyle** et la couleur de trait dans **ctx.strokeStyle**.

## Commençons à coder

Avant d’attaquer l’animation, nous allons commencer à manier les **outils de tracage**.

### Chemins et traits simples

Nous allons commencer par tracer un trait simple qui va traverser tous le canvas.

Essayez le code suivant:

```javascript
ctx.beginPath();              // commence à tracer un chemin
ctx.moveTo(, 20);             // défini le premier point de tracage à la position (0, 20)
ctx.lineTo(canvas.width, 30); // Tracer une ligne jusqu'à la position (canvas.width, 30). canvas.width désigne la largeur du canvas (500 dans notre exemple).
ctx.stroke();                 // Indique au canvas de dessiner le chemin tracé depuis le beginPath
```

[Voir le résultat][3]

### Chemins et courbes de bézier

#### La notion de courbe de bézier

Une courbe de bézier est définie par 4 points :

- Deux points désignant le début et la fin du trait.
- Deux points appelés **poignées** permettant de contrôler la courbe.

![][4]

#### Application en canvas

Essayez le code suivant :

```javascript
ctx.beginPath();
ctx.moveTo(, 20);
ctx.bezierCurveTo(canvas.width/3, canvas.height, 2*canvas.width/3, , canvas.width, 20);
ctx.stroke();
```

[Voir le résultat][5]

**De la même façon, la procédure consiste à:**

- commencer un chemin,
- se placer à une certaine position,
- effectuer un traçage (courbe de bézier),
- terminer le traçage (**ctx.stroke()**).

Intéressons nous plus particulièrement au traçage de la courbe de bézier avec l’appel de **ctx.bezierCurveTo**.

##### bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)

Cette fonction prends en argument les coordonnées du premier point de contrôle **(cp1x, cp1y)**, du deuxième point de contrôle **(cp2x, cp2y)** et du point final **(x, y)**. A noter que le point de début est le point sur lequel on s’est placé au moyen de **moveTo**.

**Dans notre exemple, les deux points de contrôle sont placés ainsi :**

![][6]

### Ajout de l’animation

Pour animer notre courbe de bézier, nous allons faire varier les 4 points de notre courbe en fonction du temps.

En javascript, il y a deux moyen d’effectuer une animation :

- <del>Au moyen de **setInterval** permettant d’appeler une fonction par interval de temps régulier.</del>
- <del>Au moyen de **setTimeout** permettant d’appeler une fonction après un temps donné.</del>
- **[UPDATE 2011]** Il est maintenant recommandé d’utiliser **requestAnimationFrame** qui est l’équivalent de setTimeout mais destiné à l’animation donc plus performant. [Plus d’informations içi (en)][7]

La première approche est parfaite pour une animation **“statique”, avec peu d’intéraction**.

La seconde approche est intéressante lorsque l’animation **doit être contrôlée** (intéraction). En effet, cette approche consiste à appeler setTimeout à chaque cycle d’animation.

Nous choisirons d’utiliser **setInterval**, plus simple et plus adaptée à notre tutoriel.

#### Approche linéaire

Commençons simplement par une **évolution linéaire des points**.

Essayez le code suivant :

```javascript
var i = 0; // variable fonction du temps
var cycle = function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height); // clean the canvas
  var y = Math.abs(canvas.height - (i % (2 * canvas.height))); // y évolue par rebond entre 0 et canvas.height au cours du temps (linéarité)
  ctx.beginPath();
  ctx.moveTo(0, y);
  ctx.bezierCurveTo(
    canvas.width / 3,
    canvas.height / 2,
    (2 * canvas.width) / 3,
    canvas.height / 2,
    canvas.width,
    y
  );
  ctx.stroke();
  i++;
};
setInterval(cycle, 30); // lance le cycle chaque 30 millisecondes
```

[Voir le résultat][8]

Pour l’instant les poignées sont fixes et l’évolution linéaire de **y** donne un effet de rebond peu intéréssant.

C’est pour cela que nous abandonnons l’idée d’une évolution linéaire des positions au cours du temps pour l’approche sinusoïdale.

#### Approche sinusoïdale

Comme nous l’avons vu, l’évolution linéaire n’est pas adaptée pour ce genre d’animation (effet de rebond). Il faudrait rendre l’animation plus fluide.

Pour cela, nous allons utiliser **une évolution sinusoïdale des positions au cours du temps**.

Essayez le code suivant :

```javascript
var i = 0; // variable fonction du temps
var cycle = function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  var offset = i / 20;
  var y = ((Math.sin(offset) + 1) * canvas.height) / 2; // y varie de 0 à canvas.height
  var cpy1 = (Math.cos(offset) + 0.5) * canvas.height; // les poignées évoluent également de façon sinusoïdale
  var cpy2 = canvas.height - cpy1;
  ctx.beginPath();
  ctx.moveTo(0, y);
  ctx.bezierCurveTo(
    canvas.width / 3,
    cpy1,
    (2 * canvas.width) / 3,
    cpy2,
    canvas.width,
    y
  );
  ctx.stroke();
  i++;
};
setInterval(cycle, 30);
```

[Voir le résultat][9]

### Peaufinage

#### Amélioration du style du trait

Essayez le code suivant :

```javascript
ctx.strokeStyle = "rgba(80,150,240,0.5)"; // couleur bleu avec opacité de 50%
ctx.lineWidth = 5; // épaisseur de trait de 5 pixels
var i = 0;
var cycle = function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  var offset = i / 20;
  var y = ((Math.sin(offset) + 1) * canvas.height) / 2;
  var cpy1 = (Math.cos(offset) + 0.5) * canvas.height;
  var cpy2 = canvas.height - cpy1;
  ctx.beginPath();
  ctx.moveTo(0, y);
  ctx.bezierCurveTo(
    canvas.width / 3,
    cpy1,
    (2 * canvas.width) / 3,
    cpy2,
    canvas.width,
    y
  );
  ctx.stroke();
  i++;
};
setInterval(cycle, 30);
```

[Voir le résultat][10]

#### Ajout de plusieurs courbes

Pour avoir un effet plus accrochant, nous allons ajouter plusieurs courbes de bézier avec un décalage temporel entre elles.

Nous allons également attribuer plusieurs styles aux différentes courbes.

```javascript
var numberOfLines = 5;
var i = 0;
var cycle = function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  for (var j = 0; j < numberOfLines; ++j) {
    var offset = (i + j * 10) / 20;
    ctx.lineWidth = 1 + 2 * (numberOfLines - j); // épaisseur variable en fonction de la ligne
    ctx.strokeStyle = "rgba(80,150,240," + (j / 5 + 0.1) + ")"; // opacité variable en fonction de la ligne
    var y = ((Math.sin(offset) + 1) * canvas.height) / 2;
    var cpy1 = (Math.cos(offset) + 0.5) * canvas.height;
    var cpy2 = canvas.height - cpy1;
    ctx.beginPath();
    ctx.moveTo(0, y);
    ctx.bezierCurveTo(
      canvas.width / 3,
      cpy1,
      (2 * canvas.width) / 3,
      cpy2,
      canvas.width,
      y
    );
    ctx.stroke();
  }
  i++;
};
setInterval(cycle, 30);
```

[Voir le résultat][11]

### Aller plus loin

Il est possible de continuer encore plus loin en ajoutant l’**évolution de plusieurs paramètres en fonction du temps**.
Pour conclure, voici la démonstration finale:

```javascript
var i = 0;
var cycle = function () {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  for (var j = 0; j < numberOfLines; ++j) {
    ctx.lineWidth = 1 + 2 * (numberOfLines - j);
    ctx.strokeStyle =
      "rgba(100,200," +
      Math.floor(Math.abs(Math.cos(i / 80) * 256)) +
      "," +
      (j / 5 + 0.1) +
      ")";
    var offset = (i + j * 10 * Math.abs(Math.cos(i / 100))) / 20;
    var y = ((Math.sin(offset) + 1) * canvas.height) / 2;
    var cpy1 = (Math.cos(offset) + 0.5) * canvas.height;
    var cpy2 = canvas.height - cpy1;
    ctx.beginPath();
    ctx.moveTo(0, y);
    ctx.bezierCurveTo(
      canvas.width / 3,
      cpy1,
      (2 * canvas.width) / 3,
      cpy2,
      canvas.width,
      y
    );
    ctx.stroke();
  }
  i++;
};
setInterval(cycle, 30);
```

[Voir le résultat][12]

Nous avons ajouté:

- L’évolution de la **couleur** au cours du temps.
- L’évolution du **décalage entre les courbes** au cours du temps.

Ce tutoriel vise à présenter canvas comme une librairie très simple d’utilisation et haut niveau grâce au langage javascript.

Blog Posts