However, I saw interested people, and I think it’s the right time to write a blog post about some design choices. I’ll start off with luminance and I’ll speak about spectra in another blog post because I truly think spectra starts to become very interesting (I have my own shading language bundled up within, which is basically GLSL on steroids).

luminance and how it copes with fast and as-stateless-as-possible graphics

Origins

luminance is a library that I wrote, historically, in Haskell. You can find the package here if you’re interested – careful though, it’s dying and the Rust version has completely drifted path with it. Nevertheless, when I ported the library to Rust, I imported the same “way of programming” that I had·have in Haskell – besides the allocation scheme; remember, I’m a demoscener, I do care a lot about performance, CPU usage, cache friendliness and runtime size. So the Rust luminance crate was made to be hybrid: it has the cool functional side that I imported from my Haskell codebase, and the runtime performance I wanted that I had when I wrote my two first 64k in C++11. I had to remove and work around some features that only Haskell could provide, such as higher-kinded types, type families, functional dependencies, GADTs and a few other things such as existential quantification (trait objects saved me here, even though I don’t use them that much in luminance now).

I have to admit, I dithered a lot about the scope of luminance — both in Haskell and Rust. At first, I thought that it’d be great to have a “base” crate, hosting common and abstracted code, and “backend” crates, implementing the abstract interface. That would enable me to have several backends – OpenGL, Vulkan, Metal, a software implementation, something for Amiigaaaaaaa, etc. Though, time has passed, and now, I think it’s:

• Overkill.
• A waste of framework.

The idea is that if you need to be very low-level on the graphics stack of your application, you’re likely to know what you are doing. And then, your needs will be very precise and well-defined. You might want very specific piece of code to be available, related to a very specific technology. That’s the reason why abstracting over very low-level code is not a good path to me: you need to expose as most as posssible the low-level interface. That’s the goal of luminance: exposing OpenGL’s interface in a stateless, bindless and typesafe way, with no or as minimal as possible runtime overhead.

More reading here.

Today

Today, luminance is almost stable – it still receives massive architecture redesign from time to time, but it’ll hit the 1.0.0 release soon. As discussed with kvark lately, luminance is not about the same scope as gfx’s one. The goals of luminance are:

• To be a typesafe, stateless and bindless OpenGL framework.
• To provide a friendly experience and expose as much as possible all of the OpenGL features.
• To be very lightweight (the target is to be able to use it without std nor core).

To achieve that, luminance is written with several aspects in mind:

• Allocation must be explicitely stated by the user: we must avoid as much as possible to allocate things in luminance since it might become both a bottleneck and an issue to the lightweight aspect.
• Performance is a first priority; safety comes second. If you have a feature that can be either exclusively performant or safe, it must then be performant. Most of the current code is, for our joy, both performant and safe. However, some invariants are left around the place and you might shoot your own feet. This is an issue and some reworking must be done (along with tagging some functions and traits unsafe).
• No concept of backends will ever end up in luminance. If it’s decided to switch to Vulkan, the whole luminance API will and must be impacted, so that people can use Vulkan the best possible way.
• A bit like the first point, the code must be written in a way that the generated binary is as small as possible. Generics are not forbidden – they’re actually recommended – but things like crate dependencies are likely to be forbidden (exception for the gl dependency, of course).
• Windowing must not be addressed by luminance. This is crucial. As a demoscener, if I want to write a 64k with luminance, I must be able to use a library over X11 or the Windows API to setup the OpenGL context myself, set the OpenGL pointers myself, etc. This is not the typical usecase – who cares besides demosceners?! – but it’s still a good advantage since you end up with loose coupling for free.

The new luminance

luminance has received more attention lately, and I think it’s a good thing to talk about how to use it. I’ll add examples on github and its docs.rs online documentation.

I’m going to do that like a tutorial. It’s easier to read and you can test the code in the same time. Let’s render a triangle!

Note: keep in mind that you need a nightly compiler to compile luminance.

Getting your feet wet

I’ll do everything from scratch with you. I’ll work in /tmp:

$ cd /tmp

First thing first, let’s setup a lumitest Rust binary project:

$ cargo init --bin lumitest
  Created binary (application) project
$ cd lumitest

Let’s edit our Cargo.toml to use luminance. We’ll need two crates:

• The luminance crate.
• A way to open the OpenGL context; we’ll use GLFW, so the luminance-glfw crate.

At the time of writing, corresponding versions are luminance-0.23.0 and luminance-glfw-0.3.2.

Have the following [dependencies] section

[dependencies]
luminance = "0.23.0"
luminance-glfw = "0.3.2"

$ cargo check

Everything should be fine at this point. Now, let’s step in in writing some code.

extern crate luminance;
extern crate luminance_glfw;

use luminance_glfw::{Device, WindowDim, WindowOpt};

const SCREEN_WIDTH: u32 = 960;
const SCREEN_HEIGHT: u32 = 540;

fn main() {
  let rdev = Device::new(WindowDim::Windowed(SCREEN_WIDTH, SCREEN_HEIGHT), "lumitest", WindowOpt::default());
}

The main function creates a Device that is responsible in holding the windowing stuff for us.

Let’s go on:

match rdev {
  Err(e) => {
    eprintln!("{:#?}", e);
    ::std::process::exit(1);
  }

  Ok(mut dev) => {
    println!("let’s go!");
  }
}

This block will catch any Device errors and will print them to stderr if there’s any.

Let’s write the main loop:

'app: loop {
  for (_, ev) in dev.events() { // the pair is an interface mistake; it’ll be removed
    match ev {
      WindowEvent::Close | WindowEvent::Key(Key::Escape, _, Action::Release, _) => break 'app,
      _ => ()
    }
  }
}

This loop runs forever and will exit if you hit the escape key or quit the application.

Setting up the resources

Now, the most interesting thing: rendering the actual triangle! You will need a few things:

type Position = [f32; 2];
type RGB = [f32; 3];
type Vertex = (Position, RGB);

const TRIANGLE_VERTS: [Vertex; 3] = [
  ([-0.5, -0.5], [0.8, 0.5, 0.5]), // red bottom leftmost
  ([-0., 0.5], [0.5, 0.8, 0.5]), // green top
  ([0.5, -0.5], [0.5, 0.5, 0.8]) // blue bottom rightmost
];

Position, Color and Vertex define what a vertex is. In our case, we use a 2D position and a RGB color.

You have a lot of choices here to define the type of your vertices. In theory, you can choose any type you want. However, it must implement the Vertex trait. Have a look at the implementors that already exist for a faster start off!

Important: do not confuse between [f32; 2] and (f32, f32). The former is a single 2D vertex component. The latter is two 1D components. It’ll make a huge difference when writing shaders.

The TRIANGLE_VERTS is a constant array with three vertices defined in it: the three vertices of our triangle. Let’s pass those vertices to the GPU with the Tess type:

// at the top location
use luminance::tess::{Mode, Tess, TessVertices};

// just above the main loop
let triangle = Tess::new(Mode::Triangle, TessVertices::Fill(&TRIANGLE_VERTS), None);

This will pass the TRIANGLE_VERTS vertices to the GPU. You’re given back a triangle object. The Mode is a hint object that states how vertices must be connected to each other. TessVertices lets you slice your vertices – this is typically enjoyable when you use a mapped buffer that contains a dynamic number of vertices.

We’ll need a shader to render that triangle. First, we’ll place its source code in data:

$ mkdir data

Paste this in data/vs.glsl:

layout (location = 0) in vec2 co;
layout (location = 1) in vec3 color;

out vec3 v_color;

void main() {
  gl_Position = vec4(co, 0., 1.);
  v_color = color;
}

Paste this in data/fs.glsl:

in vec3 v_color;

out vec4 frag;

void main() {
  frag = vec4(v_color, 1.);
}

And add this to your main.rs:

const SHADER_VS: &str = include_str!("../data/vs.glsl");
const SHADER_FS: &str = include_str!("../data/fs.glsl");

Note: this is not a typical workflow. If you’re interested in shaders, have a look at how I do it in spectra. That is, hot reloading it via SPSL (Spectra Shading Language), which enables to write GLSL modules and compose them in a single file but just writing functions. The functional programming style!

Same thing as for the tessellation, we need to pass the source to the GPU’s compiler to end up with a shader object:

// add this at the top of your main.rs
use luminance::shader::program::Program;

// below declaring triangle
let (shader, warnings) = Program::::from_strings(None, SHADER_VS, None, SHADER_FS).unwrap();

for warning in &warnings {
  eprintln!("{:#?}", warning);
}

Finally, we need to tell luminance in which framebuffer we want to make the render. It’s simple: to the default framebuffer, which ends up to be… your screen’s back buffer! This is done this way with luminance:

use luminance::framebuffer::Framebuffer;

let screen = Framebuffer::default([SCREEN_WIDTH, SCREEN_HEIGHT]);

And we’re done for the resources. Let’s step in the actual render now.

The actual render: the pipeline

luminance’s approach to render is somewhat not very intuitive yet very simple and very efficient: the render pipeline is explicitly defined by the programmer in Rust, on the fly. That means that you must express the actual state the GPU must have for the whole pipeline. Because of the nature of the pipeline, which is an AST (Abstract Syntax Tree), you can batch sub-parts of the pipeline (we call such parts nodes) and you end up with minimal GPU state switches. The theory is as following:

• At top most, you have the pipeline function that introduces the concept of shading things to a framebuffer.
  • Nested, you find the concept of a shader gate. That is, an object linked to its parent (pipeline) and that gives you the concept of shading things with a shader.
    • Nested, you find the concept of rendering things. That is, can set on such nodes GPU states, such as whether you want a depth test, blending, etc.
      • Nested, you find the concept of a tessellation gate, enabling you to render actual Tess objects.

That deep nesting enables you to batch your objects on a very fine granularity. Also, notice that the functions are not about slices of Tess or hashmaps of Program. The allocation scheme is completely ignorant about how the data is traversed, which is good: you decide. If you need to borrow things on the fly in a shading gate, you can.

Let’s get things started:

use luminance::pipeline::{entry, pipeline};

entry(|_| {
  pipeline(&screen, [0., 0., 0., 1.], |shd_gate| {
    shd_gate.shade(&shader, |rdr_gate, _| {
      rdr_gate.render(None, true, |tess_gate| {
        let t = ▵
        tess_gate.render(t.into());
      });
    });
  });
});

We just need a final thing now: since we render to the back buffer of the screen, if we want to see anything appear, we need to swap the buffer chain so that the back buffer become the front buffer and the front buffer become the back buffer. This is done by wrapping our render code in the Device::draw function:

dev.draw(|| {
  entry(|_| {
    pipeline(&screen, [0., 0., 0., 1.], |shd_gate| {
      shd_gate.shade(&shader, |rdr_gate, _| {
        rdr_gate.render(None, true, |tess_gate| {
          let t = ▵
          tess_gate.render(t.into());
        });
      });
    });
  });
});

You should see this:

As you can see, the code is pretty straightforward. Let’s get deeper, and let’s kick some time in!

use std::time::Instant;

// before the main loop
let t_start = Instant::now();
// in your main loop
let t_dur = t_start.elapsed();
let t = (t_dur.as_secs() as f64 + t_dur.subsec_nanos() as f64 * 1e-9) as f32;

We have the time. Now, we need to pass it down to the GPU (i.e. the shader). luminance handles that kind of things with two concepts:

• Uniforms.
• Buffers.

Uniforms are a good match when you want to send data to a specific shader, like a value that customizes the behavior of a shading algorithm.

Because buffers are shared, you can use buffers to share data between shader, leveraging the need to pass the data to all shader by hand – you only pass the index to the buffer that contains the data.

We won’t conver the buffers for this time.

Because of type safety, luminance requires you to state which types the uniforms the shader contains are. We only need the time, so let’s get this done:

// you need to alter this import
use luminance::shader::program::{Program, ProgramError, Uniform, UniformBuilder, UniformInterface, UniformWarning};

struct TimeUniform(Uniform);

impl UniformInterface for TimeUniform {
  fn uniform_interface(builder: UniformBuilder) -> Result<(Self, Vec), ProgramError> {
    // this will fail if the "t" variable is not used in the shader
    //let t = builder.ask("t").map_err(ProgramError::UniformWarning)?;

    // I rather like this one: we just forward up the warning and use the special unbound uniform
    match builder.ask("t") {
      Ok(t) => Ok((TimeUniform(t), Vec::new())),
      Err(e) => Ok((TimeUniform(builder.unbound()), vec![e]))
    }
  }
}

The UniformBuilder::unbound is a simple function that gives you any uniform you want: the resulting uniform object will just do nothing when you pass values in. It’s a way to say “— Okay, I don’t use that in the shader yet, but don’t fail, it’s not really an error”. Handy.

And now, all the magic: how do we access that uniform value? It’s simple: via types! Have you noticed the type of our Program? For the record:

let (shader, warnings) = Program::::from_strings(None, SHADER_VS, None, SHADER_FS).unwrap();

See the type is parametered with three type variables:

• The first one – here Vertex, our own type – is for the input of the shader program.
• The second one is for the output of the shader program. It’s currently not used at all by luminance by is reserved, as it will be used later for enforcing even further type safety.
• The third and latter is for the uniform interface.

You guessed it: we need to change the third parameter from () to TimeUniform:

let (shader, warnings) = Program::::from_strings(None, SHADER_VS, None, SHADER_FS).unwrap();

And that’s all. Whenever you shade with a ShaderGate, the type of the shader object is being inspected, and you’re handed with the uniform interface:

shd_gate.shade(&shader, |rdr_gate, uniforms| {
  uniforms.0.update(t);

  rdr_gate.render(None, true, |tess_gate| {
    let t = ▵
    tess_gate.render(t.into());
  });
});

Now, change your fragment shader to this:

in vec3 v_color;

out vec4 frag;

uniform float t;

void main() {
  frag = vec4(v_color * vec3(cos(t * .25), sin(t + 1.), cos(1.25 * t)), 1.);
}

And enjoy the result! Here’s the gist that contains the whole main.rs.

• The lib.rs / main.rs files, that get rendered as front page on docs.rs. This is important because we want people to have nice onboardings when hitting the official documentations of our crates.
• The README file — often README.md, that gets automatically rendered as HTML when you end up on the project’s GitHub page. This page should provide as many as possible hints and information about what the project is and how to use it.

However, sometimes, I just don’t want to bother writing twice the same thing and honestly, I don’t really know whether the README file is a good place to write an onboarding section, since that should also be included in your Rust documentation on docs.rs.

So… I’ve been thinking of a way to fix that, without really investing too much time in it. But lately, I came to the realization that I often have this pattern:

1. Write the onboarding documentation in my lib.rs or main.rs. For instance, I’m pretty proud of the onboarding documentation of warmy. It’s exhaustive, easy for newcomers, it has plenty of links and explanations and it renders pretty nice on docs.rs.
2. Write a header in the README file with badges etc. and then copy the Rust onboarding documentation in the readme.

Here, (2.) is a manual and annoying task: I open my editor, make a block selection of the documentation, store it in a buffer, apply a smart macro on it to remove the Rust annotation and then paste the result in the README after having purged it from the previous documentation… That’s tedious and not very interesting.

cargo sync-readme to the rescue!

So, yesterday, I decided to start working on a small tool that would automate all this for me. The idea is the following:

• cargo sync-readme synchronizes your README (the file specified by the readme key in your Cargo.toml, or just README.md by default) with the entrypoint of your library or binary crate (by default, lib.rs or main.rs, or what is defined at the path key in your manifest).
• In order to perform the synchronization, you need to have put a special marker so that the command is instructed where to put the synchronized documentation.
  • The <!-- cargo-sync-readme --> marker must lie on a single line where you want the documentation to be inserted in your README.
  • Post generation, this marker will disappear and will get replaced by the synchronized documentation, surrounded by two markers: <!-- cargo-sync-readme start> and <!-- cargo-sync-readme end -->.

This is really all you have to do. cargo sync-readme will take care of the rest for you. There’re two hypothesis that the command requires to be true, though:

• Your README file should be a Markdown-formatted file. It doesn’t have to be, but since Rust’s documentation is written in Markdown, it should be.
• You use the //! annotation to write your documentation. This is currently how cargo sync-readme works. It doesn’t have to be solely using this annotation on longer term, but currently, this is the only annotation supported. More can be added if needed.

Basically, insert the marker once, and run cargo sync-readme. Every time you change your Rust documentation, just call cargo sync-readme once again to synchronize the documentation in your README file.

On workspace crates

Currently, cargo sync-readme doesn’t work with workspace crates. You will have to go into each of the workspace’s members to run cargo sync-readme if you want to synchronize their respective READMEs.

Conclusion

cargo sync-readme is already available on crates.io for you to use. You can install it as a development tool with the following command:

cargo install cargo-sync-readme

Disclaimer: after having published cargo-sync-readme, I was told that there is already another cargo plugin, cargo-readme, that already does that. Indeed, that crate does more or less the same job. However, the way it does it is very different. First, it uses a template file while cargo-sync-readme lets you use your README file without having to depend on a template. Also, cargo-readme has special semantics in its template (like {{crate_name}}, etc.) while cargo-sync-readme is simpler and just requires a single marker. To sum up: cargo-readme is heavier and is likely to require you to break your file into two separate files but contains more customization options while cargo-sync-readme only requires a single line in your README and will synchronize from within that same file.

Feel free to comment, open issues, drink beers, share that awesome bear driving a sausage podracer and most of all… keep the vibes!

• cargo-sync-readme on GitHub
• cargo-sync-readme on crates.io

The manual dispatch problem

The idea is simple: you are writing a crate and want to expose an API to people. You want them to know which type they can use with a given operation (let’s call it update). However, the actual implementation of this update function is not performed directly by your API but is deferred to a backend implementation. Some people usually like to do that with several crates; in my case, I really don’t care and let’s think in terms of types / modules instead.

There are several ways to do this. Let’s start with a nobrainer.

The first attempt: dynamic dispatch

use std::marker::PhantomData;

// This type serves as to reify typing information at runtime and also serves as “public contract”.
// What it means is that this type gives you all the possible logical types you can use.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum Type {
  Int,
  UInt,
  Float,
  Bool
}

// We will use a very small abstraction to represent the update function (and the backend).
// Var<B, T> is just a variable of type T represented in the backend B.
#[derive(Debug)]
pub struct Var<B, T> where B: ?Sized {
  name: String,
  _b: PhantomData<*const B>,
  _t: PhantomData<*const T>,
}

impl<B, T> Var<B, T> {
  // Just create a variable of a given name, whatever its type and backend.
  pub fn new(name: &str) -> Self {
    Var {
      name: name.to_owned(),
      _b: PhantomData,
      _t: PhantomData,
    }
  }
}

impl<B, T> Var<B, T> where B: Backend, T: Interface {
  // Update the value of the variable.
  //
  // For simplicity, I don’t include a mutable reference to the backend, because that is not the
  // topic of this blog article. However, you might want to if you want to be able to, for instance,
  // change the value in a map stored in the backend, for instance. But whatever.
  pub fn update(&mut self, value: &T) {
    B::update(self, value);
  }
}

// The interface (i.e. public API) trait. This serves as a “anything implementing that can be used
// with the API.” It simply associates a Type that is, if you remember, an exhaustive list of types
// that can be used (and reified at runtime).
trait Interface {
  const TY: Type;
}

impl Interface for i32 {
  const TY: Type = Type::Int;
}

impl Interface for u32 {
  const TY: Type = Type::UInt;
}

impl Interface for f32 {
  const TY: Type = Type::Float;
}

impl Interface for bool {
  const TY: Type = Type::Bool;
}

// The backend (i.e. private implementations) trait. An implementation should implement this trait
// to implement the actual update of a variable for a given context / backend. Notice the Interface
// constraint on the T type parameter.
trait Backend {
  fn update<T>(var: &mut Var<Self, T>, value: &T) where T: Interface;
}

impl Backend for () {
  fn update<T>(var: &mut Var<Self, T>, _: &T) where T: Interface {
    // We can reify the type of the variable at runtime thanks to the associated constant value.
    // However, you can see that we have no way to actually inspect the value. This is due to the
    // fact our update function is universally quantified on T: we cannot observe T (i.e. know its
    // exact type) from within the implementation. That might be a problem.
    match T::TY {
      Type::Int => println!("setting {} to int", var.name),
      Type::UInt => println!("setting {} to unsigned int", var.name),
      Type::Float => println!("setting {} to float", var.name),
      Type::Bool => println!("setting {} to bool", var.name),
    }
  }
}

Let’s dig in. The idea of this solution is to have a trait, Interface, that is used to create a set of types that can be used in the API with the update function on the Var type. The implementation is deferred to a backend via the Backend trait, that contains the interface of the implementation. Basically, the Var::update function will select at compile-time which backend to use, that will in its turn observe the type of the variable at runtime — see the match block. This is not ideal as we will have branching. We would like a better way to do it.

The second attempt: static dispatch

Instead of dynamically dispatching the types of the variable, we can play around with it at compile-time. That requires some changes but in the end it’s pretty clear what we need to do:

use std::marker::PhantomData;

// We don’t need the Type enum anymore so I just removed it. However, even with that solution, we
// could still want to keep it around.
#[derive(Debug)]
pub struct Var<B, T> where B: ?Sized, T: ?Sized {
  name: String,
  _b: PhantomData<*const B>,
  _t: PhantomData<*const T>,
}

impl<B, T> Var<B, T> {
  pub fn new(name: &str) -> Self {
    Var {
      name: name.to_owned(),
      _b: PhantomData,
      _t: PhantomData,
    }
  }
}

impl<B, T> Var<B, T> where B: Backend, T: Interface {
  pub fn update(&mut self, value: &T) {
    // Notice how now, we use the update method from the Interface and not the Backend! Important
    // change, as you will see.
    T::update(self, value)
  }
}

// The interface trait loses the associated constant and gets a method, update. This method must
// work for any backend (i.e. types that implement Backend), since it’s our public facing trait.
trait Interface {
  fn update<B>(var: &mut Var<B, Self>, value: &Self) where B: Backend;
}

// We can then implement it for all our types by selecting manually the update_* method we want.
impl Interface for i32 {
  fn update<B>(var: &mut Var<B, Self>, value: &Self) where B: Backend {
    B::update_i32(var, value);
  }
}

impl Interface for u32 {
  fn update<B>(var: &mut Var<B, Self>, value: &Self) where B: Backend {
    B::update_u32(var, value);
  }
}

impl Interface for f32 {
  fn update<B>(var: &mut Var<B, Self>, value: &Self) where B: Backend {
    B::update_f32(var, value);
  }
}

impl Interface for bool {
  fn update<B>(var: &mut Var<B, Self>, value: &Self) where B: Backend {
    B::update_bool(var, value);
  }
}

// The trait backend is now a list of methods that will be available to the Interface’s
// implementors.
trait Backend {
  fn update_i32(var: &mut Var<Self, i32>, value: &i32);
  fn update_u32(var: &mut Var<Self, u32>, value: &u32);
  fn update_f32(var: &mut Var<Self, f32>, value: &f32);
  fn update_bool(var: &mut Var<Self, bool>, value: &bool);
}

/// Implementing the backend trait now gives us a power we didn’t have back then in solution 1: we
// now can observe the type of the variable and, then, we can actually do useful things with it, as
// displaying it!
impl Backend for () {
  fn update_i32(var: &mut Var<Self, i32>, value: &i32) {
    println!("setting {} to int {}", var.name, value);
  }

  fn update_u32(var: &mut Var<Self, u32>, value: &u32) {
    println!("setting {} to unsigned int {}", var.name, value);
  }

  fn update_f32(var: &mut Var<Self, f32>, value: &f32) {
    println!("setting {} to float {}", var.name, value);
  }

  fn update_bool(var: &mut Var<Self, bool>, value: &bool) {
    println!("setting {} to bool {}", var.name, value);
  }
}

We change the definition of the Backend trait to have all the functions dispatched statically. Then, using the Interface trait, we now have one information we didn’t have in the first example: the actual, concrete type of the variable. We can then call the right function from the Backend trait.

To sum up, because all of this is starting to be a bit confusing:

• The Interface trait is the trait used to restrict the public API (i.e. which types can be used publicly).
• The Backend trait is the trait to implement when providing the actual implementation.

However, if we add more types, that solution won’t scale easily. The problem is that we have the typing information in several places (at the impl level and in a static list in a trait). It would be much easier if we could, somehow, force an impl to exist in another trait. Basically, I want to remove those update_* and use impls instead.

The third and final solution: inferred static dispatch

I have no idea how to call that way of doing but I like to think of it as inferred constraints. The idea is almost the same as the second solution but instead of declaring the list of functions that can be used in the implementation of the Interface trait, we will just create a generic dependency between the Interface trait and Backend. The advantage will also be that we don’t have to worry about the name of the function anymore, since it will be polymorphic.

Let’s go.

use std::marker::PhantomData;

#[derive(Debug)]
pub struct Var<B, T> where B: ?Sized, T: ?Sized {
  name: String,
  _b: PhantomData<*const B>,
  _t: PhantomData<*const T>,
}

impl<B, T> Var<B, T> {
  pub fn new(name: &str) -> Self {
    Var {
      name: name.to_owned(),
      _b: PhantomData,
      _t: PhantomData,
    }
  }
}

// Wouhouh, some changes here. We go back to the first solution by using the update method of the
// Backend trait, but notice how we bind the Backend trait to the Interface by using Backend<T>.
impl<B, T> Var<B, T> where T: Interface, B: Backend<T> {
  pub fn update(&mut self, value: &T) {
    B::update(self, value)
  }
}

// This trait is now a bit dumb and even dangerous as it’s very easy to implement it. In a perfect
// Rust world, we would have sealed traits — i.e. we could only implement it from the inside of the
// current crate.
trait Interface {}

impl Interface for i32 {}

impl Interface for u32 {}

impl Interface for f32 {}

impl Interface for bool {}

// The backend trait now has an associated type parameter that represents the variable type. What
// it means is that we will be able to implement the update function for all types of our choices…
// and still observe the type, since from inside the update function, it’s not universally
// quantified anymore!
trait Backend<T> {
  fn update(var: &mut Var<Self, T>, value: &T);
}

impl Backend<i32> for () {
  fn update(var: &mut Var<Self, i32>, value: &i32) {
    println!("setting {} to int {}", var.name, value);
  }
}

impl Backend<u32> for () {
  fn update(var: &mut Var<Self, u32>, value: &u32) {
    println!("setting {} to unsigned int {}", var.name, value);
  }
}

impl Backend<f32> for () {
  fn update(var: &mut Var<Self, f32>, value: &f32) {
    println!("setting {} to float {}", var.name, value);
  }
}

impl Backend<bool> for () {
  fn update(var: &mut Var<Self, bool>, value: &bool) {
    println!("setting {} to bool {}", var.name, value);
  }
}

This solution is quite interesting because of the use of the type parameter in the Backend trait. It enables you to implement the Backend trait and still observe (i.e. know) the type of the variable you’re playing with. Compare with the first solution, where we were completely generic on the T type.

In luminance, I use the last solution to allow a clear distinction between a set of public types and a set of matching implementations. Notice in the last solution the Interface trait, which is now reduced to something pretty dumb. It would be easy for anyone to implement it for their own types and then implement Backend<TheirType> for TheirBackend. Rust doesn’t offer a way to have sealed traits so far, so my current solution to this is to mark the trait unsafe (to scare people and tell them not to implement the trait). However, a clear and first-class citizen language construct for this would be highly appreciated.

That’s all for me today. If you have any question about such a design, I’d be happy to answer your questions on Reddit, as usual.

Keep the vibes!

This article serves as an announcement for glsl-0.13.

I’ve been working on glsl-0.13 for a few days now since my previous blog entry about adding pest to glsl – and no, the current code is not pest-based, it’s still good old nom. Lately, I’ve been wanting to enhance my glsl-quasiquote crate to add variable interpolation. I think I will dedicate a whole article to variable interpolation in GLSL because it’s actually tricky to get done right – without duplicating a whole parser or introducing problematic code with pest (see my last article).

Since I’m not a programmer who solves problems that don’t exist, I have problems to get resolved in other crates and binary projects of mine (mostly demoscene and demoscene tooling). However, I’ve been spending days solving those problems because they’re not related to demoscene only: pretty much anyone who would like to cope with shaders might be interested.

The glsl crate prior to 0.13

The glsl crate provides you with:

• A GLSL450 parser. I wrote the parser with nom back then by implementing the strict OpenGL Shading Language Spec (here). That parser works mostly on strings and byte slices (I really doubt people use the byte slice interface and I might deprecate it).
• The parser parses into an Abstract Syntax Tree – AST for short. That AST is, as the name implies, a tree that contains typed nodes. It’s a bit more complicated than having a BTreeMap for instance, because each nodes and levels are completely typed. You can picture the AST as both a type tree and value tree instead of just a value tree.
• Before 0.13, transforming the AST was tedious, because you had to pattern match on the whole structure of the AST, and since it’s a type tree, it’s really, really boring to do so.
• One typical transformation that I always need in several crates of mine is construction. Building ASTs was overwhelming and complicated because you had to create the tree by hand. To solve that issue, I introduced the glsl-quasiquote crate, that enables you to create the AST out of a regular GLSL string. I hit some issues with that, like the impossibility to have typing information exchanged between two compiler phases (the procedural macros are all evaluated before the rest, making it impossible to have type inference like in let x: Expr = glsl!{…};. I will try to fix that later.
• The quasiquote crate works great for static ASTs but as soon as you want to build dynamic ones ( i.e. that depend on variables for instance), since glsl-quasiquote doesn’t have variable interpolation (yet!), you’re back to the boring by-hand construction.

glsl-0.13 comes with several new features and enhancements to partially fix those points that I will explain in this blog entry.

The new features!

First, let’s talk about contribution. I received a contribution (both an issue and a PR, how amazing!) from @JDemler about the #define preprocessor pragma. Those were not taken into account so far and he provided the fix to add them! As for all other pragmas, those have to lay in the global scope – they’re not expected to be found in function bodies, for instance.

Thanks for your contribution! :)

Then, a lot of work has been done around the glsl::syntax module. This module contains all the AST types and some methods were added to, for instance, create functions, variable declarations, if-else blocks, etc. Those functions were made the most general as possible and heavily depend on From / Into, allowing for very short oneliners to create complex AST nodes. The best example for this is the Statement::declare_var that declares a new variable as a Statement. Most of the inner AST nodes won’t ever be needed in the public interface, so those functions hide them from you and give you the easy way to build bigger nodes.

There is an example below that uses Statement::declare_var. Keep on reading! :)

Not all AST nodes have helper methods for construction. The good thing is that adding a new function shouldn’t be a breaking change, so I’ll keep adding them as needed – if you have a specific need for one, feel free to open an issue, I will make the change. That might be surprising but since I haven’t witnessed lots of people using the crate yet, I don’t implement what I don’t need yet – but as soon as someone tells me they need something, either I immediately review the PR, or plan some time to make the patch myself.

Finally, the biggest feature which will be explained in further details in this blog post: AST visitors. AST visitors are the way I imagined would be the best to traverse an AST in order to mutate some nodes, all the nodes, filter, query information, etc. It’s like lenses for glsl! – but trust me: it’s way lighter! :D

Visiting ASTs

AST visitors solve a problem I had when implementing a specific feature in spectra. I needed to be able to change all the references to a given identifier in all the AST at once. Either the identifier is used in an expression assigned to a new variable, returned from a function or passed as argument to a function, I needed to catch that identifier… and change its name.

That was quite of a desperate challenge without a proper solution. Imagine: I would have to write the code to change the identifier myself and… find ALL the places where identifiers might appear in any AST. This is possible, but that would drive many developers mad – especially whevener the glsl crate changes.

So I came up with a better solution. I will not drop you a technical term and have you read Wikipedia, I would dislike that. I will just explain from bottom up why it’s designed this way and why I think it’s the best solution.

Visiting summarized

The idea is that pattern-matching on an identifier might appear in several places in an AST. So whatever solution we choose, we will have to find all those spots and call a function that states:

Hey there. Here is an Identifier. I give you a &mut Identifier so that you can change it.

An Identifier is an AST (a really simple one, but still is). So you might want to implement that function on Identifier… but what happens when your AST is an Expr, and that expr is a variable – that is, Expr::Var(identifier_here)? You will want to implement your function on Expr also, then. And here you see that you need a trait, because, as said earlier, the AST is a type tree.

However, what trait? We could imagine implementing that trait only on AST types that have an Identifier as field or variant. But the most general AST node, TranslationUnit, is a non-empty list of ExternalDeclarations. If we want to visit that, we won’t be able to type match and pass down our function transforming identifiers.

We see that we will need to implement that trait for all AST types so that they can pass the function down the AST to a node that actually has an Identifier.

And since we’re doing it with Identifier, we might want to do it with any AST node. But if we do that, we cannot pass one single function anymore…

The Visitor

So you need an object that will be able to treat an Identifier… or a TranslationUnit, or anything AST. This is a bit boring to implement, but we need a trait that enables a type to visit any AST node:

trait Visitor {
  fn visit_identifier(&mut self, _: &mut Identifier);
  fn visit_translation_unit(&mut self, _: &mut TranslationUnit);
  // …
}

This is great, because if a type implements Visitor, it means that we can call visit_identifier on it if we have an Identifier! When we will be implementing our traversing function, we will just have to carry around a mutable reference to an object implementing Visitor, and call the right function depending on the AST node / type we are at!

We also use mutable references here so that we can also mutate information as we sink into the AST. This might be very useful to know at which block depth we are at, or if we’re in a function’s body, etc.

Something important with that trait though: the current implementation (from this article) would be very boring to implement, because it has a lot of visit_* methods. What if we’re only interested in Identifier? We don’t want to have to implement visit_translation_unit because we don’t care.

A simple fix to that is to give all those visit_* methods a default implementation… that does nothing.

trait Visitor {
  fn visit_identifier(&mut self, _: &mut Identifier) {}
  fn visit_translation_unit(&mut self, _: &mut TranslationUnit) {}
  // …
}

Let’s try it!

struct ReplaceIdentifier<'a> {
  replacement: &'a str
}

impl<'a> Visitor for ReplaceIdentifier<'a> {
  fn visit_identifier(&mut self, ident: &mut Identifier) {
    *ident = self.replacement.clone().into()
  }
}

And that’s all! We now have a visitor that can be used to traverse any AST and change any Identifier to what we have set. For instance:

let mut ast = …;
let mut visitor = ReplaceIdentifier { replacement: "foobar" }

// wait, how do we pass the visitor to the AST here?

Argh, we’re still missing something!

Hosting visitors

We need a visit function, like:

fn visit<V>(ast: &mut TranslationUnit, visitor: &mut V) where V: Visitor

So let’s write it!

fn visit<V>(ast: &mut TranslationUnit, visitor: &mut V) where V: Visitor {
  for external_decl in ast {
    // ah.
  }
}

We cannot call visit again on ExternalDeclaration. Seems like we need another trait! :D

trait Host {
  fn visit<V>(&mut Self, visitor: &mut V) where V: Visitor;
}

Here, a type that implements Host means that it can call a Visitor on itself, and might pass it down to children AST if any. Since we’re going to implement Host for all our AST types, we will be able to do something like this:

impl Host for TranslationUnit {
  fn visit<V>(&mut Self, visitor: &mut V) where V: Visitor {
    visitor.visit_translation_unit(self); // first, we have the visitor visit the AST node

    // then, for all children, we pass down the visitor!
    for external_decl in self {
      external_decl.visit(visitor);
    }
  }
}

And here we go. We are able to pass down the visitor, that will be called for each node. If you have provided an implementation for a given visit_*, it will get invoked, otherwise, the default implementation will fire – and it does nothing.

A simple optimization can be done, here. Since you might know that you’re done at a given level regarding your visitor, we could add a way to make a Host stop visiting and go any deeper. For this, we introduce a simple enum:

enum Visit {
  Children, // keep visiting children
  Parent // stop visiting, go back to parent
}

And we change all the Visitor methods to return a Visit. That will give us the information we need when implementing Host::visit now:

impl Host for TranslationUnit {
  fn visit<V>(&mut Self, visitor: &mut V) where V: Visitor {
    let visit = visitor.visit_translation_unit(self); // first, we have the visitor visit the AST node

    if visit == Visit::Children {
      // then, for all children, we pass down the visitor!
      for external_decl in self {
        external_decl.visit(visitor);
      }
    }
  }
}

We also need to change the default implementation of the visit_* methods. My choice was to have them return Visit::Children by default, because I think it’s a saner default – if people don’t want to go any deeper in the AST, they will just have to dummy-implement the right method.

And we are done! The actual implementation is a bit more complex than that but is really really close to what is described in this article. I’ll give you the example from the official documentation so that can you can see how it’s really used:

use glsl::syntax::{CompoundStatement, Expr, SingleDeclaration, Statement, TypeSpecifierNonArray};
use glsl::visitor::{Host, Visit, Visitor};
use std::iter::FromIterator;

let decl0 = Statement::declare_var(
  TypeSpecifierNonArray::Float,
  "x",
  None,
  Some(Expr::from(3.14).into())
);

let decl1 = Statement::declare_var(
  TypeSpecifierNonArray::Int,
  "y",
  None,
  None
);

let decl2 = Statement::declare_var(
  TypeSpecifierNonArray::Vec4,
  "z",
  None,
  None
);

let mut compound = CompoundStatement::from_iter(vec![decl0, decl1, decl2]);

// our visitor that will count the number of variables it saw
struct Counter {
  var_nb: usize
}

impl Visitor for Counter {
  // we are only interested in single declaration with a name
  fn visit_single_declaration(&mut self, declaration: &mut SingleDeclaration) -> Visit {
    if declaration.name.is_some() {
      self.var_nb += 1;
    }

    // do not go deeper
    Visit::Parent
  }
}

let mut counter = Counter { var_nb: 0 };
compound.visit(&mut counter);
assert_eq!(counter.var_nb, 3);

Future work

The current state of Visitor is great but there is a drawback: your AST has to be mutable. You might want to only traverse it read-only but have your visitor mutated. I might then modify slightly the Visitor trait and Host one with Host::visit_mut if I think it’s needed.

Feel free to experiment around. Next work planned for glsl – besides contributions – quasiquoting variable interpolation.

Keep the vibes!

It’s been a while I haven’t written anything on my blog. A bit of refreshment doesn’t hurt much, what do you think?

As a demoscener, I attend demoparties, and there will be a very important and fun one in about a month. I’m rushing on my 3D application so that I can finish something to show up, but I’m not sure I’ll have enough spare time. That being said, I need to be able to represent smooth moves and transitions without any tearing. I had a look into a few Haskell spline libraries, but I haven’t found anything interesting – or not discontinued.

Because I do need splines, I decided to write my very own package. Meet smoothie, my BSD3 Haskell spline library.

Why splines?

A spline is a curve defined by several polynomials. It has several uses, like vectorial graphics, signal interpolation, animation tweening or simply plotting a spline to see how neat and smooth it looks!

Splines are defined using polynomials. Each polynomials is part of the curve and connected one-by-one. Depending on which polynomial(s) you chose, you end up with a different shape.

For instance, 1-degree polynomials are used to implement straight lines.

As you can see, we can define a few points, and interpolate in between. This is great, because we can turn a discrete set of points into lines.

Even better, we could use 3-degree polynomials or cosine functions to make each part of the spline smoother:

We still have discrete points, but in the end, we end up with a smooth set of points. Typically, imagine sampling from the spline with time for a camera movement. It helps us to build smooth moves. This is pretty important when doing animation. If you’re curious about that, I highly recommend having a look into key frames.

Using splines in Haskell

So I’ve been around implementing splines in Haskell the most general way as possible. However, I don’t cover – yet? – all kinds of splines. In order to explain my design choices, I need to explain a few very simple concepts first.

Sampling

A spline is often defined by a set of points and polynomials. The first point has the starting sampling value. For our purpose, we’ll set that to 0:

let startSampler = 0

The sampling value is often Float, but it depends on your spline and the use you want to make of it. It could be Int. The general rule is that it should be orderable. If we take two sampling values s and t, we should be able to compare s and t (that’s done through the typeclass constraint Ord in Haskell).

So, if you have a spline and a sampling value, the idea is that sampling the spline with startSampler gives you the first point, and sampling with t with t > startSampler gives you another point, interpolated using points of the spline. It could use two points, three, four or even more. It actually depends on the polynomials you use, and the interpolating method.

In smoothie, sampling values have types designed by s.

Control points

A spline is made of points. Those points are called control points and smoothie uses CP s a to refer to them, where s is the sampling type and a the carried value.

Although they’re often used to express the fact that the curve should pass through them, they don’t have to lie on the curve itself. A very common and ultra useful kind of spline is the B-spline.

With that kind of spline, the property that the curve passes through the control points doesn’t hold. It passes through the first and last ones, but the ones in between are used to shape it, a bit like magnets attract things around them.

Keep in mind that control points are very important and used to define the main aspect of the curve.

Polynomials

Polynomials are keys to spline interpolation. They’re used to deduce sampled points. Interpolation is a very general term and used in plenty of domains. If you’re not used to that, you should inquiry about linear interpolation and cubic interpolation, which are a very good start.

Polynomials are denoted by Polynomial s a in smoothie, where s and a have the same meaning than in CP s a.

Getting started with smoothie

Types and constraints

smoothie has then three important types:

• CP s a, the control points
• Polynomial, the polynomials used to interpolate between control points
• Spline s a, of course

The whole package is parameterized by s and a. As said earlier, s is very likely to require an Ord constraint. And a… Well, since we want to represent points, let’s wonder: which points? What kind of points? Why even “points”? That’s a good question. And this is why you may find smoothie great: it doesn’t actually know anything about points. It accepts any kind of values. Any? Almost. Any values that are in an additive group.

“What the…”

I won’t go into details, I’ll just vulgarize them so that you get quickly your feet wet. That constraint, when applied to Haskell, makes a to be an endofunctor – i.e. Functor – and additive – i.e. Additive. It also requires it to be a first-class value – i.e. its kind should be * -> *.

With Functor and Additive, we can do two important things:

• First, with Functor. It enables us to lift computation on the inner type. We can for instance apply a single function inside a, like *k or /10.
• Then, with Additive. It enables us to add our types, like a + b.

We can then make linear combinations, like ak + bq. This property is well known for vector spaces.

The fun consequence is that providing correct instances to Functor and Additive will make your type useable with smoothie as carried value in the spline! You might also have to implement Num and Ord as well, though.

Creating a spline

Creating a spline is done with the spline function, which signature is:

spline :: (Ord a, Ord s) => [(CP s a, Polynomial s a)] -> Spline s a

It takes a list of control points associated with polynomials and outputs a spline. That requires some explainations… When you’ll be sampling the spline, smoothie will look for which kind of interpolation method it has to use. This is done by the lower nearest control point to the sampled value. Basically, a pair (cp,polynomial) defines a new point and the interpolation method to use for the curve ahead of the point.

Of course, the latest point’s polynomial won’t be used. You can set whatever you want then – protip: you can even set undefined because of laziness.

Although the list will be sorted by spline, I highly recommend to pass a sorted list, because dealing with unordered points might have no sense.

A control point is created by providing a sample value and the carried value. For instance, using linear’s V2 type:

let cp0 = CP 0 $ V2 1 pi

That’s a control point that represents V2 1 pi when sampling is at 0. Let’s create another:

let cp1 = CP 3.341 $ V2 0.8 10.5

Now, let’t attach a polynomial to them!

Hold that for me please

The simplest polynomial – wich is actually not a polynomial, but heh, don’t look at me that way – is the 0-degree polynomial. Yeah, a constant function. It takes the lower control point, and holds it everwhere on the curve. You could picture that as a staircase function:

You might say that’s useless; it’s actually not; it’s even pretty nice. Imagine you want to attach your camera position onto such a curve. It will make the camera jump in space, which could be desirable for flash looks!

Use the hold Polynomial to use such a behavior.

Oh yeah, it’s straightforward!

1-degree functions often describe lines. That is, linear is the Polynomial to use to connect control points with… straight lines.

Have fun on the unit circle!

One very interesting Polynomial is cosine, that defines a cosine interpolation, used to smooth the spline and make it nicer for moves and transitions.

Highway to the danger zone

If you’re crazy, you can experiment around with linearBy, which, basically, is a 1-degree polynomial if you pass id, but will end up in most complex shapes if you pass another function – (s -> s). Dig in documentation on hackage for further information.

Sampling our spline

Ok, let’s use a linear interpolation to sample our spline:

let spl = spline [(cp0,linear),(cp1,hold)]

Note: I used hold as a final polynomial because I don’t like using undefined.

Ok, let’s see how to sample that. smoothie exports a convenient function for sampling:

smooth :: Ord s => Spline s a -> s -> Maybe a

smooth spl s takes the sampling value s and maybe interpolate it in the spl spline.

“Maybe? Why aren’t you sure?”

Well, that’s pretty simple. In some cases, the curve is not defined at the sampling value you pass. Before the first point and after, basically. In those cases, you get Nothing.

That’s not the end

I wrote smoothie in a few hours, in a single day. You might have ideas. I want it to be spread and widely used by awesome people. Should you do graphics programming, sound programming, animation or whatever implying splines or smoothness, please provide feedback!

For people that would like to get contributing, here’s the github page and the issue tracker.

If no one comes up with, I’ll try to add some cubic interpolation methods, like hermitian splines, and one of my favorite, the famous Catmull Rom spline interpolation method.

As always, have fun hacking around, and keep doing cool stuff and sharing it!

Rust has this feature called move semantics. By default, the move semantics are enforced. For instance:

fn foo_move<T>(x: T)

This function says that it expects a T and need to move it in. If you don’t want to move it, you have to borrow it. Either immutable or mutably.

fn foo_borrow<T>(x: &T)
fn foo_borrow_mut<T>(x: &mut T)

Now, when you move a value around, it’s possible that you don’t use that value anymore. If you look at the foo_move function, is very likely that we’ll not use that T object after the function has returned. So Rust knows that x will go out of scope and then its memory must be invalidated and made available to future values. This is very simple as it will happen on the stack, but it can get a bit tricky.

Rust doesn’t have the direct concept of destructors. Or does it? Actually, it does. And it’s called the Drop trait. If a type implements Drop, any value of this type will call a specific function for disposal when it goes out of scope. This is akin to running a destructor.

struct Test;

impl Drop for Test {
  fn drop(&mut self) {
    println!("drop called!");
  }
}

Whenever a value of type Test goes out of scope / must die, it will call its Drop::drop implementation and then its memory will be invalidated.

Ok, now let’s get into my problem.

Moving out of a field

Consider the following code:

struct A;

struct B;

struct Foo {
  a: A,
  b: B
}

impl Foo {
  fn take(self) -> (A, B) {
    (self.a, self.b)
  }
}

fn main() {
  let foo = Foo { a: A, b: B };
  let (a, b) = foo.take();
}

The implementation of Foo::take shows that we move out of Foo – two, actually. We move the a: A field out of Foo and b: B out of Foo. Which means that we destructured Foo. The call to Foo::take in the main function demonstrates how you would use that function.

Now consider this. A and B here are opaque type we don’t want to know the implementation. But keep in mind they represent scarce resources – like UUID to important resources we must track in the Foo object. Consider this new code:

struct A;

struct B;

struct Foo {
  a: A,
  b: B
}

impl Drop for Foo {
  fn drop(&mut self) {
    // something tricky with self.a and self.b
  }
}

impl Foo {
  fn take(self) -> (A, B) {
    (self.a, self.b) // wait, that doesn’t compile anymore!
  }
}

You would get the following error:

error[E0509]: cannot move out of type Foo, which implements the Drop trait

As you can see, Rust doesn’t allow you to move out of a value which type implements Drop, and this is quite logical. When Foo::take returns, because of self going out of scope, it must call its Drop::drop implementation. If you have moved out of it – both a: A and b: B fields, the Drop::drop implementation is now a complete UB. So Rust is right here and doesn’t allow you to do this.

But imagine that we have to do this. For insance, we need to hand over both the scarce resources a and b to another struct (in our case, a (A, B), but you could easily imagine a better type for this).

There’s a way to, still, implement Foo::take with Foo implementing Drop. Here’s how:

impl Foo {
  fn take(mut self) -> (A, B) {
    let a = mem::replace(&mut self.a, unsafe { mem::uninitialized() });
    let b = mem::replace(&mut self.b, unsafe { mem::uninitialized() });
    
    mem::forget(self);
    
    (a, b)
  }
}

There’s a few new things going on here. First, the mem::replace function takes as first parameter a mutable reference to something we want to replace by its second argument and returns the initial value the mutable reference pointed to. Because mem::replace doesn’t deinitialize any of its argument, I like to think of that function as a move-swap. It just moves out the first argument and put something in the hole it has made with its second argument.

The unsafe function, mem::uninitialized, is a bit special as it bypasses Rust’s normal memory-initialization and actually doesn’t do anything. However, there’s no specification about what this function really does and you shouldn’t be concerned. What you just need to know is that this function just gives you uninitialized memory.

However, if we just returned (a, b) right after the two mem::replace calls, the Drop::drop implementation would run at the end of the function, and it would run badly, because of the now uninitialized data you find in the self.a and self.b fields. It could still be the old values. Or it could be garbage. We don’t care. We mustn’t read from there. Rust provide a solution to this, and this is the mem::forget function. This function is like dropping your value… without calling its Drop::drop implementation. It’s an escape hatch. It’s a way to invalidate a value and in our case that function is super handy because self now contains uninitialized data!

And here we have a complete working Foo::take function.

So what’s the problem again?

The problem is that I used to function I wish I didn’t:

• mem::uninitialized, which is, as the docs state, incredibly hazardous.
• mem::forget, which is not unsafe in the Rust idea of safety, but still has some kind of very nasty unsafety deep in it – it’s very easy to leak resources if you don’t pay extra attention.

The problem is that Rust doesn’t allow you to move out of a value which implement Drop even if you know that you’ll forget it. Rust doesn’t currently have a primitive / function to express both principles at the same time: forgetting and moving out of a Drop value.

This had me to come to the realization that I would like an interface like this:

fn nodrop<T, F, A>(
  x: T,
  f: F
) -> A
where T: Drop,
      F: FnOnce(T) -> A

This function would give you the guarantee that the closure will not drop its argument but would still leak it, temporarily giving you the power to move out of it. You will also notice that if you want to have A = T, it’s possible: that would mean you destructure a value and re-build it back again inside the same type, which is still sound.

However, this function would make it very easy to leak any field you don’t move out. This is actually the same situation as with mem::forget: if you forget to mem::replace a field before calling mem::forget, you end up in the exact same situation.

I agree it’s a very niche need, and if you’re curious about why I need this, it’s because of how buffers are handled in luminance. The Buffer<T> type has an internal RawBuffer as field that holds GPU handles and internal details and a PhantomData<T>. It’s possible to convert from one type to the other but both implement Drop, so you have to implement the hack I just presented in this blog post to make both conversions. With my nodrop function, the code would be way easier, without needing to unfold unsafe blocks. Something like this would be possible:

pub fn to_raw(self) -> RawBuffer {
  mem::nodrop(self, |buffer| buffer.raw) // combine mem::forget and mem::replace + uninitialized
}

What do you peeps think of such a function? For sure that would add possible easy leaks, that’s a drawback I find very difficult not to agree with. However, I just wanted to share my little experience of Tuesday evening.

That’s all for me. Thanks for having read me, I love you. Keep the vibes!

The glsl crate enables you to parse a GLSL-formatted input (raw string or byte slice) into an AST you can manipulate in Rust.

It’s very likely you will never have to work with that AST representation directly. Instead, you might be interested in all the possible outcomes you can get from using the glsl crate:

• Parse a file, like a scene.glsl, and get its AST representation in Rust.
• Pass that AST to a writer, for instance, a transpiler, to convert from the GLSL to SPIR-V or HLSL.
• Algorithmically enhance or enrich the GLSL AST without having to cope with raw strings.
• Extract information from the GLSL source code (reflection).
• Etc.

Lately, in spectra, I’ve been working on a more abstract way to write shaders in GLSL. The idea is that I need to ship the library with some GLSL. The typical way people do this is by embedding a static string into your library / application, like so:

const SOME_VERTEX_SHADER: &str =
"void main() {
  // …
}";

You can also use the include_str! standard macro to read it from a file at compile-time.

The cheddar crate provides you with an enriched version of GLSL (the Cheddar language), and the integration in spectra is pretty much seamless. The GLSL is parsed from Cheddar, transpiled to the GLSL AST and then the whole thing is passed luminance that acts as a rendering backend of spectra. Becauses some AST transformation is needed, the glsl crate is used in cheddar, and some GLSL must be added in order to provide a smoother and nicer experience within spectra.

The problem kicks in that transformation part. Since Cheddar is parsed directly into memory as an AST (via the cheddar crate), how could we transform and add things to values from cheddar?

The hard and manual way: the constructor syntax

Pretty much all of the glsl crate is public. There’s no invariant, so no need to hide anything. It’s possible to create, for instance, a AssignmentExpr by simply calling its constructor syntax:

let assignment_expr = AssignmentExpr {
  // fields here
  };

This is the regular way to go, but if you look at some types, such as the SimpleStatement, you’ll get that it can get very noisy and verbose very quickly. So that’ll work, but that’ll also be very incomfortable to work with.

The advantage of constructing and transforming that way is that you can destructure and pattern-match ASTs.

Enter the nice solution: quasiquoting

As a Haskeller, I’ve been very frustrated by that construction problem, thinking that there must be an easier and less noisy way to do so. That reminds me of all the EDSLs I wrote in my Haskeller life and some very, very sweet embedded languages, like SQL, C or Java, directly into Haskell. That is done via something we call quasiquoting. Quasiquoting is a general concept but in our case, applies to embedded languages.

The concept is simple: you write in a foreign language in a quasiquoter in your host language (Haskell or Rust). The compiler then recognizes the quasiquoter and executes some code at compile time. Once it’s done, it replaces the quasiquoted statement with the result of its computation.

One good example of quasiquoting is postgresql-query, a Haskell quasiquoting library for SQL. SQL queries can be built with regular Haskell code but they can also be built out of a quasiquoter, like so:

-- some code elided for simplicity here
pqQuery [sqlExp|SELECT u.id, u.name, u.age
                FROM users AS u ^{cond}
                ORDER BY ^{ord}|]

The [sqlExp|…|] notation uses the quasiquoter syntax: the sqlExp is the quasiquoter to use, and everything between the two pipes are the content / input to pass the quasiquoter. The compiler just reads that, executes some code defined in the postgresql-query library and if it runs correctly, the resulting expression is inserted directly at the place of use as if nothing has happened. Brillant, right? :)

Having written glsl, that seemed like a perfect – maybe even wanted and mandatory? – opportunity to me to introduce GLSL quasiquoting into the Rust environment. Maybe it’ll also bring some people onto the glsl project – I really need hands, especially because the SPIR-V transpiler doesn’t exist yet!

So, here you go. glsl-quasiquote-0.1 was released today! The crate provides you with two macros: glsl! and glsl_str!. Both are procedural macros that requires a nightly compiler and the proc_macro_non_items feature. They will both output a TranslationUnit, that represents a whole shader AST.

The glsl! AST works the same way a quasiquoter from Haskell: instead of delimiting your GLSL code with pipes, you write them inside parens or brackets, like so:

glsl!{
  void main() {
  }
}

The glsl_str! macro does the exact same thing but expects a literal string as input. This is due to the fact that quasiquoting in Rust is a bit tricky – who’s looking at me like I was about to write an RFC? – because regular macros and procedural macros eat Rust tokens as inputs, forcing their content to be Rust-friendly syntax. Well, GLSL is not: the #version and #extension pragmas need newlines at the end, so the following will not work:

glsl!{
  #version 330 core
  void main() {
  }
}

Instead, you must use the glsl_str! quasiquoter:

glsl_str!{"
  #version 330 core

  void main() {
  }
"}

It’s a bit of an unaesthetica and pretty weird syntax but we don’t really have a choice (so far).

Whenever a GLSL is incorrectly formatted, you’ll get a compiler error. For instance, the following:

glsl!{
  void main() 3 {
  }
}

generates the following rustc output:

error: proc macro panicked
  --> tests/lib.rs:26:11
   |
26 |     let _ = glsl!{
   |  ___________^
27 | |     void main() 3 {
28 | |     }
29 | |   };
   | |___^
   |
   = help: message: GLSL error: Err(ParseError { kind: Many1, info: "void main (  ) 3 {  }" })

error: aborting due to previous error

The crate was released today, so it needs a lot of love, attention and testing. I’m adding support for it in spectra for my experiences, so I should be updating it if I find anything wrong with it.

Feel free to use it, and have fun! I’m awaiting your feedback!

Keep the vibes!

This article serves as an announcement to a new crate: proc-macro-faithful-display.

Enhancing faith in displaying Rust tokens

The problem

I’ve been around procedural macros in Rust for a few weeks now – in order to write my glsl-quasiquote crate. Quickly, I discovered that most types cannot be inspected. For instance, an Ident has no methods to get the underlying identifier (as a &str for instance). The only way to do so is to allocate a String, for instance, via a Display use, as in:

let ident_str = format!("{}", ident);

Now, imagine you have a fully formatted stream of GLSL tokens flowing in. I’ve already blogged lately about the fact Rust has some specific rules that will prevent you to write preprocessor pragmas. The only way to authorize them was to implement a hack (explained in the blog article).

Lately, I was working on some not-so-trivial glsl transformations in another project when I hit a parse error. I was surprised, because the glsl crate contains more than 130 unit tests about parsing. So I thought “Well, okay, it’s alright, I might have forgotten a very specific case not covered in my nom implementation. I’ll just get a small reproducible sample and use it as a new integration test in glsl”. That kind of reasoning is very important to me: if you find a bug, first thing to do (if you plan to fix it) is to write a unit test that fails first. This is very important because when the test succeeds, you have solved your problem. If someone provides a contribution later and that the test breaks again, you will have just shielded the project against a test regression. Seriously, I know it’s boring but: write tests.

So I wrote a test, a very simple one (this is actually an integration test, since I’ve found the error in a project using glsl). And… the test passed. I was so surprised: “So that code breaks in my crate, but succeeds in the integration test suite?! Well, wait. That means that the parser is actually correct. The problem might come from the way the parser is used… or the input.”

So my second reaction was to have a look at where the parser was called. It was in a glsl! procedural macro invocation – in my project, I hardcoded a vertex shader with glsl-quasiquote. And then, I came to the realization and remembered. glsl-quasiquote, in order to parse the input Rust token, has to use Display on them, in order to yield a String usable by the glsl parser. The parser is okay – i.e. the integration test passes – but the input string… loses information.

If you have taken a look at the integration test just above, you should have noticed an interesting construction:

void main() {
  float x = 1. * .5;
}

This is not a semantically valid vertex shader, but it should parse. And it does parse. But if you write that vertex shader with glsl-quasiquote, what you actually write is this:

let vertex_shader = glsl!{
  void main() {
    float x = 1. * .5;
  }
};

The Rust tokenizer will eat the tokens and the Display implementation will render the stream by using spaces whenever it sees fit. It will not respect the initial whitespaces. It might yield something like this:

void main ( ) { float x = 1. * . 5 ; }

Look closely: our .5 GLSL floating point constant value (it equals 0.5) has become . and 5. rustc has transformed it into two tokens instead of a single one. This is due to the fact that this float format is not allowed in Rust and is interpreted the same way a method call would be.

The solution

So, after realizing that, I just went for a documentation addition stating that numbers cannot be expressed this way, and that you have to use a leading 0. I really disliked writing that documentation exception but I didn’t have any solution to that.

A few days later, I was thinking about glsl variable interpolation and got a mind click. In order to implement preprocessor pragmas, I used a trick with Span, that gave me positional information of tokens. And I came to the realization that I could use the same kind of trick to implement a function that would yield an object implementing Display by respecting the initial layout / formatting!

Basically, a trait – FaithfulDisplay – is implemented for all flavours of Rust tokens:

• Ident.
• Literal.
• Punct.
• Group.
• TokenTree.
• TokenStream.

All the implementations carefuly carry around the previous Span in order to pad enough spaces and newlines before they get formatted into the Formatter. This allows to reconstruct the input layout.

All this code is packaged in the proc-macro-faithful-display crate. You can find the documentation here. I use it – and tested against – the crate with glsl-quasiquote. It especially allowed me to remove all the preprocessor trick because now newlines are taken into account.

Is this viable?

Honestly, I have no idea. Currently, at the time of writing, it works like a charm. If you find any bug or weird behavior, please open an issue here. However, proc-macro hasn’t yet been stabilized and the Span type is accessible through a feature gate. All of this might change. However, I strongly think that:

• Either Rust will keep that Span type because it is really helpful (its first purpose was to provide nice error reporting).
• Either they’ll ditch it, but since quasiquoting is important and wanted (have a look at @bodil’s awesome typed-html crate for instance), something to replace it might come next.

Keep the vibes!

In this blog entry, I want to share something a bit different: instead of presenting my experiences with all those editors, I want to take some hindsight and analyze a bit more the technology and what it seriously means in terms of features and productivity. Obviously, I will reference other editors I have used a lot (I use IntelliJ a lot at work, and I am used to VS Code and Atom as well).

Current status as of March 2021: I am lost

Yeah, you read that title right. I am lost. I have been a Vim / Neovim user for something like 12 years now. I am used to the ecosystem, I have installed hundreds of plugins in the past decade, tried so many things, discovered pearls that I still use today (hello context.vim), I have been using a workflow based on tmux, Neovim and my shell that has proven very powerful and yet to be fully replaced. But — and I think it is important to make that note — I did not start coding with Vim. Today, I am 29. I started coding when I was 11, using a tool called Code::Blocks. Rapidly, I switched to Emacs – by the time, Doom Emacs did not even exist, and spent several years using it. Later, when I was between 16 and 17, I switched to Vim — I guess the modal idea got me intrigued and I felt in love with it. In 2014, I was told that Vim was getting forked for the reasons we all know and I decided to switch to the fork, called Neovim.

Since then, I have been sticking to Neovim but I do not partake in those “editor wars”. “VS Code sucks”, “how do I even exit Vim?”, “Emacs is bloated!”. I have my personal opinions on the technologies (i.e. I dislike very much the front-end ecosystem / electron, even though I think the front-end idea — i.e. running code in a browser — is an interesting idea; I just think the current technology for doing so is really bad), so obviously I will not pick something such as Atom / VS Code, but I cannot say they suck. I have tried them. I see why people like them and it would be very dishonest to say those editors suck. They really do not. Same thing applies to the products by JetBrains. In the past year, I did not understand why some people would pay money for an editor. I have to use IntelliJ at work and even though I would not pay for an editor, I start to grasp why people would actually want to pay for one. Not all people have the patience and time to tweak an editor to their taste, such as with Vim / Neovim / Emacs. For those people, editors such as VS Code, IntelliJ, Atom and others are really just superior.

Just take LSP. Configuring LSP in VS Code is a click on an install button, depending on your language. That is all. You get all the good defaults and behaviors and you can already start enjoying coding with LSP. Doing the same in an editor like Neovim is a very different experience. I am not saying it is bad; it is different. If you are, like me, someone who enjoys spending time tweaking their tools, then you should not care too much. I have a colleague at work who gave me an argument that I find very interesting: he basically wants an editor he does not have to configure, so that we knows how to use it everywhere, on any machine of any colleague. That is not a point I would make, but for someone who cares about that topic, it is a solid argument in favor of tools such as IntelliJ or VS Code.

In the previous company I was working for, I worked with @gagbo, who is an active Doom Emacs contributor, and I was surprised by the editor he was using on his laptop. He mentioned Doom and on the night home, I had a look at it, and I was really blown away. Doom Emacs (Doom for short) was a revelation to me, because it is using emacs as a productivy platform more than a simple editor. @hlissner, Doom’s author, and the Doom community, have been gathering the best of emacs and vim into a single configuration distribution. The result is so interesting and so powerful that I have been doing back and forth between Doom and Neovim. More on that below.

Lately, I have been more present in the Neovim community, contributing mostly via a plugin that I have been making: hop.nvim. That plugin is a complete rewrite from scratch of EasyMotion (I have not even looked at how they do it on their side) I made by using the Neovim Lua API directly. Obviously, it provides a much better experience than EasyMotion in Neovim, simply because it uses features such as virtual text and extended marks and does not touch the buffer, allowing to benefit from Neovim-0.5 crunchy features, such as the native LSP client and treesitter parsers. I also made a bunch of PRs to Neovim core, reading a bit on the C code, etc.

All that to say that… given the experience that I have with Neovim and Doom… I have no idea what to think about “editing” anymore. Neovim is growing and lots of interesting ideas are landing / will land in the next release. I do not really know whether people will stick around Hop, but I think it has found its place — at least, I spotted a missing piece and provided it. I am not a fan of Lua but I have to admit that it attracts more people doing some awesome things. Among the things that I think are going into the right direction:

• The native LSP client.
• The native treesitter implementation.
• Nvim Tree, a file browser written in Lua. Similar to netrw but better and much (much) faster.
• Telescope, a fuzzy finder, a bit similar to Ivy / Helm from the emacs realm. I have issues with it right now because I am used to fzf-vim and all the current sorting / picking algorithms are not up to the user experience of fzf to me. When I compare it to Ivy, it is roughly the same: Ivy’s algorithm is just better to me (it has the same refinement search mechanism as fzf’s, and it’s much faster than Telescope, especially Swiper). I think it will change in the near future as algorithms in Telescope are improved and support is added for (I hope!) fzf, but for now, the bad performances of telescope, the choice of making it pretty before focusing on the algorithms first makes it not really usable on some code bases. However, I do think it is going into the right direction and I will be looking forward it in a few weeks / months, giving it time to mature a bit and get better defaults / algorithms.
• Neogit, an implementation of the best Git client ever, magit, also from the emacs realm. I think it will take them months before it reaches the same maturity and power as magit, but I think it is cruising great.
• Octo, a GitHub-based workflow plugin allowing to list, create, open, add, remove, etc. lots of GitHub objects directly from within a Neovim buffer, streaming changes on buffer exit / save. Similar, again, to magit’s Forge, from the emacs world, even if Forge is a bit more powerful as it abstracts away the concept of “remote”. However, the edit workflow of Octo seems a bit more stable right now, so kudos!
• Probably a ton of other plugins I forgot to mention.

So what is wrong?

My experience with Doom Emacs really changed the way I look at software, and more specifically at “productivity tools.” See, my current workflow is based on tmux, Neovim and my shell, which is zsh (vanilla, I completely ditched Oh My Zsh as I find it useless and I uninstalled starship.rs a few weeks ago because I realized I hated the package manager version annotations on my prompt, that I actually never needed). For people wondering, we have spent so much time trying to install cool things that we forgot how powerful raw and vanilla zsh is. This is my current prompt:

At work, I need a bit more information (i.e. Kubernetes (k8s) namespace and context / cluster I am currently connected to and AWS), but as those information are not path-dependent, I put them in my tmux statusline instead.

The thing is… I just realized by using Doom Emacs that I do not need all of these anymore. Doom Emacs provides an environment that is very similar to my tmux + neovim + shell combo. It provides even more, depending on the packages you install. And the thing is: for each tool, emacs have more opportunities, because it is not limited by a terminal implementation (i.e. cell-grid / line based application). So for instance, you can have a k8s / AWS / docker client inside Emacs that is likely to be much much better than the one you will use in CLI (I honestly dislike kubectl a lot, it has so many switches and grepping through them by piping with rg or using some switches such as -l feels weird). You can easily see a buffer containing the list of pods / containers / whatever, that you should be able to work with the tool you already use (i.e. Ivy for instance), interact dynamically with (instead of having to type one line after another to make effects). It is even more true when you consider the actual shell: you do not need zsh anymore when using Emacs, because it has its eshell implementation that is both super weird and super nice. You want to script something for your shell? Just write ELisp. You do not have to use that horrible bash script language, and you will benefit from the whole ELisp ecosystem. Completion for commands in eshell is basically the same as completing a regular buffer, which is weird at first but actually makes a lot of sense. And you have dozens of other examples. Org-mode is one of the best plugin of Emacs, allowing to take notes, make wikis, handle tasks and calendars, in a way that feels very seamless with the rest of the Emacs ecosystem. I know some people will tell me to use another tool (I do, my current tool for that is toodoux, a tool I made, similar to task-warrior). And of course, magit, which is by far my favorite Emacs plugin. As others say it, it is hard to explain why magit is so much better than the git CLI or VS Code’s integration or basically any other editor. It is just made very well, with pretty much anything actionable from the UI, with amazing workflows and even actions you do not have easily with the CLI version.

What is an editor in 2021, anymore?

Today, when I look at Doom, at Neovim, at what people are trying to do in Lua with Neovim, I feel like I need to stop trying to implement / follow what others are doing and think a bit about whether we are doing the right thing. Neovim, currently, is going towards a very exciting direction with all the effort regarding Lua, LSP, treesitter and community plugins. But I think the problem is bigger than Neovim. And I think I know that because of how I can use emacs with Doom. I think I come back to Doom so often because they understand well what it means to create a productivity platform more than an editor. It does not mean the editor is any less good, au contraire. In Doom, there is a default package that gets installed if you ask for the project module. That package is projectile, a wonderful package that provides with you project management from within emacs. If you use emacs in daemon mode, it means that you can get the same workflow as with tmux, Neovim and a shell, but with a native implementation of this project / workspace workflow, in a much much more powerful way (because it will obviously plug in things like Ivy, allowing you to do fuzzy searching of projects, etc.). The overall experience by having a consistent platform is something I had completely ignored for years and now that Doom hit me, it hit me hard. I do not know any other platform like emacs, besides composable environments such as tmux + Neovim + shell. Yes, you have VS Code / Atom / IntelliJ / etc. that will have tons of plugins to get you terminals and other kinds of integrations, but for having used them, it is clearly not as powerful as what Doom does — and it is most of the time based on electron; big no. To sum up, Doom is a bit my VS Code: it provides this amazing productivity platform, but it is fully native, modal-centric and highly composable / customizable.

Composability is really important to me, but I have to face reality: there is no way to make a workflow such as tmux + Neovim as snappy and fast as projectile. tmux basically reimplements a terminal inside a terminal, which has a lot of implications (copy-pasting with the mouse in tmux is a challenge even Chuck Norris does not want to take). And once you turn the computer off, tmux loses everything. You have plugins, such as tmux-resurrect, that will allow to save and restore the tmux layout (sessions / windows / panes), but you will obviously lose the contents of each panes. With projectile, because it is a native emacs thing, you will not lose anything.

This whole idea has been obsessing me for months. The concept of a “productivity platform.” People laugh at emacs as being bloated but… it basically implements their shell, tmux and editor in a more elegant way — and more. Why would one laugh at that? Especially when it allows more interesting kinds of interaction.

So I have been wondering: what is a productivity platform, today, in 2021? Is it this workflow I have been using since I am 16, with tmux and Vim / Neovim? A friend on IRC told me lately that if I have been using this workflow (as others do) for so long… it has proven being good so why would I want to replace it? Even though this is a valid point, I do think this is missing the point: ask some workers to dig a hole for planting trees, they will start digging the ground with their bare hands. Later, give them a shovel and they will accept it as a better tool and will enjoy it. But does it mean it is the best tool for planting trees? What if a better tool existed? This is basically the reason why I never accept something as an ultimate solution: we can always enhance our tools. And having seen what Doom Emacs do, I do think that I have found new ideas. Not necessarily a better tool, but at least, I think Neovim needs to evolve.

When I think about Neovim, I try to focus on what makes it this tool I love: modal centric, snappy / performance, integrates well with tmux, and that is pretty much all. The integration part with tmux is needed because I have to use the TUI, which is also something that I start not liking anymore. I know since Doom that we can get rid of TUIs and make great GUIs. So what I think I want to go to with Neovim from now on is this:

• Contribute to a GUI or even make my own. I have glanced at all the current solutions and none are really exciting to me. People have basically been making window decorations around TUI buffers, which I truly do not like. Some exceptions that I might invest time in:
  • goneovim, which seems to have the more advanced “GUI” externalized features.
  • uivonim, but I will not contribute nor use it because, heck, electron.
• Contribute to neovim-ui and see where I can help with abstractions.

Something around one year ago, I chatted with core contributors, telling them that something that puzzles me a bit with the current Neovim situation is that there is no unified / consistent UI experience. Most plugins will write their own UI thing, obviously often based on TUI hacks, such as using characters as ─, ╮, ├, etc. The current situation with plenary.nvim is another interesting topic, because I think it is not the answer to my problem. Yes, it will provide an abstraction for people needing to create bordered windows / pop-ups but… the GUI really does not care about that. Technically, Neovim already makes the distinction between “buffers” and “pop-ups” and “floats”, so GUIs are free to render them the way they want, but… what if developers start using APIs, such as plenary, where they pass border arguments? How does that make sense? If you are writing a plugin that needs to list things and requires a fuzzy interaction with the user, you should not depend on something that expects anything from the UI implementators. And for this, I think Neovim is lacking abstractions. Obviously, we can discuss that kind of problems for other topics:

• Displaying messages.
• Displaying notifications (I wish Neovim used the D-Bus protocol or similar on Linux for instance).
• Fully customizable sign columns and “franges.”
• Etc. etc.

I guess some of those items are already addressed, but I have yet to see a Neovim GUI going fully “native without TUI aspects.” Maybe it already exists and I need to search again. I want to invest time in things like goneovim and some other implementations, and I really do want to make my own (maybe with Gtk or even using my own 2D/3D graphics Rust stack).

Next obsession: CLI, TUI and GUI

CLI stands for Command Line Interface; TUI for Terminal User Interface and GUI for Graphics User Interface.

Among all the things that Doom changed in my mind, there is this concept of TUI. I have been a very big user (power user?) of the CLI. Pretty much anything that I do on a computer is via the CLI. For more advanced usage, I tend to use a TUI. I only use GUIs if I have to, such as firefox, blender or a video game. However, guess what: Doom hit hard here too, because I am not using the TUI version: I am using the GUI one. And do not get it twisted, I am not using my mouse, and this is a very important and interesting point about CLI / TUI / GUI.

When talking about this CLI / TUI vs. GUI thing around me, people tend to agree, weirdly, on some misconceptions:

• CLIs and TUIs, because they are mostly implemented as terminal applications, would not rely (for most) on the mouse and then implement super good user experiences (UX): good shortcuts, good navigation through the application, easy completion, great composability, etc. The UI, on the other side, would be rather poorer, because of the limitations of the terminals: no images, only icons, which most of the time require patched fonts to render icons; weird hacks based on unicode characters to mimic UIs like borders, splits, buttons, inputs, etc.
• GUIs would rely more on the mouse and then focus less on the UX, making them harder to use for people on the keyboard, with shortcuts most of the time not that good, preventing fluid and seamless navigation on the keyboard; poor composability with other applications, etc. However, they would have much better UI, because of vector graphics images, proper UI elements such as real inputs, buttons, border, splits, different font families / sizes, etc.

These misconceptions are interesting because, as misconceptions, they are not real. You can find some terrible CLIs (i.e. npm is such a bad CLI — I had a big issue at work a few years ago when running not on purpose a command such as npm i --user, thinking it would install it in user space while it just completely ignored the unknown --user flag and installed the package globally), and you can find terrible GUIs too. However, and this is where I want to focus, GUIs are not necessarily mouse-focused, and since we can implement nice UX in TUI… we should be able to do the same in GUIs, right?

Aaaaaaaand… enter Doom, again. I am using the GUI version of emacs — on Archlinux, I am using this patched version which is a basically gccemacs, an emacs that recompiles all the Lisp as C! It obviously can accept mouse inputs so that you can click on things if you want to but… the most important still applies: you can use it exactly as you would use it in a terminal. However, because it is a GUI, you get access to much more possibilities:

• Proper “pixel scrolling.”
• Use several fonts, of different sizes, for things like Markdowns, note taking, etc.
• Proper pop-up windows.
• Pixel-perfect annotations, marks, hints and signs in your buffer.
• Images, rasterized or vector graphics.
• One of the most important part to me: proper UI elements! No more hacks!
• Even though it is not implemented yet, since we can have images, and especially vector graphics, we should be able to render git branches with pretty links and not the /|\* ASCII art mimics we see in all CLIs / TUIs.
• Etc. etc.

Today, I do think that the right direction is to allow developers to build platforms around the concept of “graphics toolkits”, and not “terminal applications.” Even for CLIs. Think about git branch. My current git branch workflow, in CLI, does not use git branch only: I have an alias for each Git commands that require a branch. For instance, if I want to switch to another branch, this is what my gs alias looks like when invoked:

This is basically a fuzzy-finder version of git switch, using fzf – if you want that script, have a look at these ones. The same feature is doable with Doom / Neovim by using the right plugin, and I have to admit that I prefer doing that in magit as it feels more “well integrated.” Of course, you will always want to have a way to compose applications, and for that, CLIs are great. Something such as kubectl get pods -l service=my-service | rg whatever. However, I am trying to challenge my own conception of “program composability” because I do think we can implement this list k8s pods -> filter them inside an UI such as the ones in Doom Emacs, without having to write a specific tool. And we can actually do it in CLI / TUI as I just showed with my gs alias, so… why not providing that kind of power natively on the platform?

Final obsession: configuration ≠ scripting

And now one of the big issue I have with pretty much any editor today (but more with Neovim as I am actively contributing to it): if you want to configure your editor, you have to code your configuration and I highly dislike that. It is possible, indeed, to reduce the quantity of code to write, but you will eventually have to get your hands dirty and write some Lua (eeew). And I have a big issue with this.

See, configuration should be stupid and limiting. It should be key = value, period. If you need a more structured way to configure things, just add sections / objects like what you can do with TOML or JSON, but that is all. Remember that a configuration file might be read by a human, and that you must do everything possible to make it super clear what the configuration state is. Configuring should be:

• Not Turing-complete. You should not have access to logical constructs, such as conditional statements / jump statements or anything that would turn your configuration language Turing-complete.
• Imports / includes should not be possible. Having to import things from a configuration file makes it harder for the application to read from it and it makes it much harder for people to know what values are currently set.
• If you really want to have “scripting” over your configuration files, use some proper languages made exactly for this purpose, such as Dhall, a template engine or something similar. Leave the choice to the user to decide whether they want to configure, or code.

There is a fundamental difference between having the power to do something and explicitly refusing that power and lacking that power. I think that configuration can be done via code, but it does not mean it should. The reason for that is mainly for cognitive complexity reasons. If you are the author of your application, you will very likely know how to script it. You will know all the quirks and all the little things to know that you will, obviously, have well documented (right?!). Your users will not have this kind of knowledge. I think it is wrong to use Lua to configure a software as it will force people to get into the documentation of the Lua API, while all they should have is a list of configuration options they can set, what setting does what and what are the possible values, and that is all. Providing more power leads to inconsistencies, broken setup and something that is pretty hard to fix without proper semantic versioning (and an actual package manager enforcing it): a slowly rotting configuration.

Rotting configuration happens when you start piling up lots of “configuration code”, using different APIs, that will eventually get deprecated or not even used anymore. If you are lucky, the application will just tell you this and that API calls are deprecated and you should switch to something else. If you are not, you will get some random crashes and failures in your applications and you will have to debug code. For configuration. And this happens a lot with Neovim.

See, blurring the line between configuration and scripting is easy, especially if you use the same language for both. Scripting is enhancing the power of an application, such as an editor or a video game, by providing new behaviors. Those behaviors (should them be native to the applications or new ones provided by plugins) are configured. If you start having to script the configuration side, you lose the distinction between both.

At work, we are using k8s a lot. In order to configure our services, we have to deploy configuration massively everywhere, and we need to generate that configuration. But see, there is a difference between “the configuration” and “generating the configuration.” The “generate part” is basically a template language. This is code, because it relies on the datacenter / cluster / environment / feature flags / etc. we want to deploy in / with. However, we do not configure the software in the template code. We pass fragments of configuration to the template engine, which generates the final configuration. And those fragments are basically exactly what I described above: key-value objects, sometimes nested to implement more complex configuration setup, but nothing else. It is basically YAML. If you do not need the complexity of the datacenter, cluster or environment, you can just run your application with a configuration file that has no code in it, just a bunch of key-value pairs.

The way Neovim treats configuration right now is via a convention, well-accepted among the plugin developers (and since I am now officially a Neovim plugin developer with hop.nvim, I obviously follow it as well). That convention is the setup function plugins expose to pass configuration (via an object often called opts for options). So people have to know whether that convention is used, they have to call that function (i.e. it is a regular Lua function call) and they have to dig in the Lua API. What I think I want to try (I think I am going to work on a plugin for that) is a way to have a central “configuration store” so that users do not have to go through this setup thing anymore — which, for the record, requires you to do something like require'the-plugin'.setup { … }, for every plugin you want to use. The way I see things would be more like this:

-- In your init.lua, for instance

require'config-store'.setup {
  telescope = {
    -- options used by telescope
  },
  hop = {
    -- options used by hop
  },
  neogit = {
    -- options used by neogit
  },
  -- etc. etc.
}

require'telescope'
require'hop'
require'neogit'

Then, each plugin, in their init.lua, could do something like this:

-- Assuming this is the plugin for hop
local config = require'config-store'.hop or require'hop.config'.defaults

This way of doing seems much more natural to me, as it limits the amount of “coding” people have to do to configure their packages, and it is not really different for package maintainers. Instead of exposing a setup function, they can just get the configuration via this config-store thing. I think I will try to experiment with this idea. Obviously, it requires plugins to adopt this config-store thing, and I do think that if people think it is an interesting idea, this should be a vanilla Lua API and not a random plugin, so that we know this config-store object is there, whatever plugins the user have installed. As discussed above with how we do that at work, I do not want to prevent people from coding / scripting their editors. But I think a clear distinction between scripting and configuring is important.

In the end

So those were my (lost) thoughts about the current situation. I might do a follow-up later in the year to see how things have evolved to me. Today, I stick around Neovim in tmux, using various scripts around fzf to make my shell a bit more interesting to use. I have to admit that I often open emacs to do three / four commits. The experience is just consistent. Navigating in projectile, Ivy and magit is unbeaten to me. The simple interactions with dired (to navigate directories a bit like with a file browser) and edit their contents is something I truly seek everywhere else, even in my shell. I recently did a quick benchmarked of Avy, the emacs implementation of EasyMotion, versus hop.nvim, and Hop is really much faster, so I do not really know what to think (I guess I should be proud of what I made 🙂). I think that Doom currently has this level of maturity that Neovim will take years to achieve, not because of talent, but because of the fact Neovim is an editor and has not been designed as being a productivity platform, while emacs was.

Keep the vibes!

Neovim and plugins

I have been in that situation where I struggle with plugins breaking every time I update, and not only in Neovim. The problem can occur pretty much anywhere. The main reason to this is simple: breaking changes happen, and must happen. Plugins maintainers might decide at some point that something must be removed, or changed. A configuration option you were using disappears or its name changes. That happens and it’s part of the how software works.

However, there is a difference between breaking changes in plugins and breaking changes in i.e. libraries / binaries we write in languages supporting package managers, such as Rust and cargo, Haskell and cabal, Python and poetry, etc. etc. Actually, there are two main differences, depending on the perspective you take to look at the problem:

• From a user perspective, software is not versioned and « they want the last updated thing. » Obviously, if you are a programmer, you know that it’s likely something is versioned, but most of the time, when you install something like a video game you like, an editor, a plugin or anything, do you really ask for a specific version? There are obviously situations where you need to ensure the versions that you use, but most of the time, people do not care.
• From a plugin author perspective, there is no tooling to ensure that you can ship a feature without breaking your users.

About the last point, when I work on a given software project, I specify the dependencies of my project, and I specify the versions of those dependencies. Using SemVer, I’m sure that if the those dependencies are correctly written, I should be able to release my software (lib or bin) without any issues on my users. There are exceptions, but those are rare and most of the time related to human errors when implementing SemVer incorrectly.

When you write a plugin, you will most likely write it in a language and ecosystem that doesn’t even support versioning. Which brings me to the main point of this article: how do you prevent breaking your users?

The git channel and the « latest » problem

Neovim plugins are often implemented in package managers like packer via Git URLs. Most of the time, foo/bar will be installed as the bar plugin, part of the org / user foo on GitHub. You can also install local plugins but that’s off topic here. When you provide the description of the plugin to install, you will most of the time provide nothing more. This will default to install and synchronize the plugin using the master branch (or whatever your local git says, like main). As a Software Engineer, to me, this is a really bad habit we all have, and I’ll explain why.

When you depend on the latest version of something, you are basically signing a contract between your local system and the remote system to keep your local version in sync with remote. If the remote gets updated, you get the changes the next time you update. The problem with this is that master contains zero information about whether an update is a breaking change or not. It’s the same reason why defaulting API calls to your API service to the latest version of the API is wrong and that you should default them to v1: because it will never change, so people have to opt-in for breaking changes instead, which is a much saner way of dealing with breaking changes.

So I’ve been thinking about this problem for quite a while now. In ecosystem like Rust, crates have to implement SemVer, so that cargo, the package manager and build system, knows how to resolve the dependency graph given your version requirements. But we don’t have that with Neovim plugins… or do we?

The solution is (partially) already there

In packer (and probably others), we can provide additional information to download (and update) plugins. For instance, packer supports the branch = …, tag = … and commit = … configuration options. So this gave me an idea. And this idea is something I would like to turn into a proposal for the Neovim community. The idea is to use both branches and tags to encode SemVer information and allow users to specify plugins a bit like you would specify dependencies in tools like cargo. In order to do that, plugin authors must accept and implement SemVer. The current way I see things is actually pretty simple:

• master, main, etc. can be used as a nightly channel. Users who don’t want to deal with this SemVer idea can just ignore the whole thing and still use their plugins the way they’ve always had.
• A triplet git tag, vM.m.p, represents a full, immutable version that cannot be changed. This would allow a user to depend on vM.m.p and be sure that the plugin would be pinned to that version. Here, M is the major version, m is the minor version and p is the patch version. Every time the plugin is modified in a way that doesn’t show on the interface (no breaking change and no non-breaking change, only internal patches), the p version is incremented.
• A pair git branch vM.m, with M the major and m the minor version. The idea is that every time a plugin gets a new non-breaking change, the m version is incremented. That would allow users to depend on vM.m to be sticky to that minor version, but still receive patches updates. More on that below.
• A single version git branch, vM, with M the major version. Every time the plugin gets a new breaking change, M is incremented. This would probably be the most interesting options for users, as it would allow them to benefit from new features without having their plugin break on an update.

In order to implement this scheme using git branches and git tags, there is one trick to implement. One a plugin author decide to make a new release, they have to do several things:

• Create a git tag. If the previous version was v1.2.3, they will either create v1.2.4, v1.3.0 or v2.0.0, depending on the kind of change.
• If they have created a new patch version:
  • They need to create the tag v1.2.4.
  • They need to update the branch v1.2 so that it now points to the same commit as v1.2.4.
  • They need to update the branch v1 so that it now points to the same commit as v1.2.4.
• If they have created a new minor version:
  • They need to create the tag v1.3.0.
  • They need to create the branch v1.3 and make it point to the same commit as v1.3.0.
  • They need to update the branch v1 so that it now points to the same commit as v1.3.0.
• IF they have created a new major version:
  • They need to create the tag v2.0.0.
  • They need to create the branch v2.0 and make it point to the same commit as v2.0.0.
  • They need to create the branch v2 and make it point to the same commit as v2.0.0.

With this approach, a user can now depend on a version and be sure not to get breaking-changes. An example for my config for hop.nvim:

use {
  'phaazon/hop.nvim',
  branch = "v1",
  config = function()
    require'hop'.setup {
      keys = 'etovxqpdygéèfblzhckisuran',
    }
  end
}

Tooling

I’m currently writing a (small) plugin, branching on package managers such as packer, to be able, from a user perspective, to get a listing of packages that can be upgraded. For instance, if you depend on telescope.nvim-0.4, if telescope.nvim-0.4.9 is released, packer should pick it up because you would have branch = v0.4 in your config (and that branch would be updated to point to git tag v0.4.9). However, if telescope-nvim-0.5 is released, that tool will provide you with a hint that a new version is available and that you need to manually select it, because it might break your configuration.

Pros. & cons.

The obvious advantage (and incentive) here is that if plugin authors accept to implement something like this, plugin stability will be an old bitter memory. People who don’t care and want to live on the bleeding edge can completely ignore this proposal and still use the master / main branch (not providing the branch unfortunately often defaults to the master branch). The other incentive here is that plugins (like the one I’m writing for the tooling) can now do more things with git tags and branches to display more information, like the number of releases, git tag annotations to show proper release notes inside Neovim, etc.

The drawbacks are not negligible: implementing such a SemVer proposal using git tags and branches is going to require a bit more work, and the tooling is clearly lacking. This is very similar to how dynamic relocatable objects (.so) are handled on most Linux systems: the actual .so file is versioned somewhere on your file system, like /usr/lib/foo.1.2.3.so, and applications / other libraries can depend on major and minor versions by using symlinks: /usr/lib/foo.1.so points to /usr/lib/foo.1.2.so, which in turns points to /usr/lib/foo1.2.3.so. git doesn’t support sticky branches (i.e. you can’t ask to make a branch reference another one, it has to reference a commit, which is always immutable), so it means that updating a version requires you to update the whole hierarchy of branches, which is a bit annoying. A tool (like a shell tool in the plugin I’m writing) could probably help with that.

So what do you think? Worth it? I think that in terms of stability, it is a missing piece of pretty much any editor supporting dynamic plugins. The « ideal » situation would be to support semantic versioning directly at the package level (which is not packer, but directly how Neovim represents package), and the actual encoding of the package versions would probably be hard to implement using only a centralized system like GitHub as there is no index (besides git tags and branches).

I belong to the category of people who enjoy composing tools. That is, I don’t use an IDE: I make my own IDE by combining several tools I like. In the end, we all use “IDEs” (we all need some kind of development environment). For the sake of generality, I will call those environments “DE” for development environments.

The tools I use are, basically:

• A terminal. Lately, I’ve been enjoying kitty a lot, for it allows me to do almost everything I do with tmux (read below).
• A shell. I’m using zsh mostly but I’ve been playing with others, such as nushell. I’m dissatisfied with zsh because I think it’s way more too complicated (I barely use 10% of its features).
• A text editor. I’ve been using lots lately, but mainly, vim / neovim.
• A git client. I simply use the git CLI (Command Line Interface) program, but also fugitive in neovim.
• A couple of other programs, such as fzf, CLI of various package managers and compilers, etc.
• I have plugins in neovim for note taking and task management, but I’ve also been using Notion at work lately to try it out.
• I used to use tmux a lot but I’m moving away from it, so I’m basically left with kitty’s own way to do the same thing.

The more that I think about all the things I use and all the things people enjoying modern environments use, the more I feel I try to “force” a workflow that used to be the right one a couple of years ago, but not necessarily today. I’m the kind of person who constantly put things into perspective and try to balance my decisions regarding the time I have, the budget (for work) and the knowledge. A couple of months / years ago, I spent a lot of time on emacs and realized that I needed to review my perspective, because even though emacs is super old, it’s fascinating how bleeding edge it still feels (and I can’t even imagine how bleeding edge it was twenty years ago!).

I want to use this blog article to ask questions and not necessarily answer them, but discuss about them. The questions are about “how we should be developing in the modern era” and is not about “is emacs better than neovim” or that kind of useless debates.

• Is tooling composition that any good?
  • The frozen world
  • The nightmare that is composition iteration
  • A small word on TUIs, the land of the unicode hacks
  • Summary of the problems
• What would be the (next) perfect productivity platform in 2022?
  • The terminal needs to change
  • Editing needs to come back to editing
  • Applications need to compose in a new, modern way
  • Applications need to change

Is tooling composition that any good?

The first question I’m wondering is that whether using several tools and composing them is actually good in 2022. For instance, the best example I have in mind is Kubernetes and fzf. At work, I have a workflow where I use Kubernetes and filter/select its output via fzf to run other commands. I do the same with git, btw. I have some scripts where I can do something like:

gr -s # equivalent to git branch | fzf | git rebase origin --auto-stash
gs # equivalent to git branch | fzf | git switch
gm # equivalent to git branch | fzf | git merge
kubectx # switch via FZF k8s clusters (kubectl command)
kubens # same but with k8s namespaces
# etc. etc.

The frozen world

All of that seems to be pretty good. We can leverage the power of small tools such as git, kubectl and fzf and compose them. Shell pipes allow to connect applications together, reading and writing from and to stdin and stdout.

The “main platform”, the “DE” is then the terminal and the shell, and building a DE requires two main ingredients:

• A set of programs, each of them doing one thing right. fzf is excellent at building a list of items and let the user pick one of them, for instance. kubectl allows to operate Kubernetes resources one operation by one operation.
• Some “glue” to combine the results of the programs. This is typically the shell, with its pipes and output pushed to the terminal.

However, I think that even though all of that seems pretty great, it suffers from a major drawback: everything is text and everything is static. See, all of the programs I mentioned here are CLI, not TUI (Text User Interface). That is, the UX is the following:

1. The user enters a command in their terminal, starting with the program name, passing arguments.
2. The program runs, might have side effects on remote resources, etc.
3. The program finishes and displays its results.

That way of working has been a default in the industry for decades. If the program printed more than one terminal page, you will have to scroll to find your information back up. Once you find the information you need, how do you pick that information? If you are using a terminal that doesn’t support hinting, you will have to use your mouse (which completely defeats the purpose of using CLI / TUI applications to me) or the keyboard-base navigation system of your terminal to make selections, which is, let’s be honest, really poor in most terminal. If, like me, you use a terminal supporting hinting (i.e. being able to enter a mode that will allow you to visually select parts of the screen by simply typing a few characters — similar to my hop.nvim plugin, but for the terminal), you will be able to copy parts of the screen, but that’s all. If a program returned a JSON array, it will cost you a lot of keystrokes to reduce the list and, for instance, use an item in the array as input of another curl request, for instance.

The nushell has a very interesting concept to solve that kind of problem. Programs write lines of text as output, but they can also write cells, which is a nushell encoding that allows it to “speak the same language.” It comes with some built-in programs such as open that will be able to recognize a lot of formats (JSON, XML, YAML, TOML, etc.) and convert them into cells, allowing to display them in the terminal in a very convenient and “smart” way. However, it doesn’t change the next problem: composition iteration.

The nightmare that is composition iteration

I think pretty much every programmer out there can relate to the following: you will oftentimes run a command, see its result, then run the command again, piping it to a filter command or sort or field extractor like [jq]. If the output is too long, it’s likely you will output into a file and will work on that file (which is basically a cached version of your command output ;) ).

Iterating on a “session” is a pretty bad experience in a terminal to me. To my knowledge, it would be quite easy to fix by simply allowing to automatically cache the result of all commands, and get access to it via a shell variable (such as what we have with $? for the last command status, for instance). Some hacks exist to recompute the last command (i.e. $(!!)) but it will still re-run the last command.

I thought nushell supported that, because the variable support and Nu language are pretty excellent, but to my surprise, that shell doesn’t have that. Maybe it’s a technical challenge, but I really doubt it. We work with computers with at least 8 GB of RAM these days and most of us have between 16 and 32 GB of RAM. I don’t think it would be that hard to support.

But even if we had that caching… it would still require us to run a command, look at a static text, run a filter command on it, look at the new output that would be appended to the screen… it doesn’t seem super nice in terms of UX to me. And imagine having to change the second or third command in the pipe list while you already have six pipes. Duh. The problem, to me, is that the terminal application scope is being overloaded. The CLI is great when we want to run a command and expect a report. As soon as we need to work with data, I think the CLI is already lacking features.

A small word on TUIs, the land of the unicode hacks

And now, let’s talk about TUIs. As a lot of people, I’m using TUIs, so don’t get what I’m about to say twisted. I use neovim as my daily editor driver, and so far, I haven’t really found a way out and use something else. However, it’s not because nothing better exists that what we use is perfect (far from that).

I have always despised TUIs. I think the idea, which dates from a while, was a fun and interesting idea back then, when graphical elements and graphics kits were not mature and not a thing yet. But today, we know we can have graphical elements that align at the pixel level. We know that we can have real vector images in applications. We can use the GPU to draw arbitrary shapes and some terminals (text-based only!) use the GPU to render glyphs (text), and then people use TUIs that will use the glyphs to mimic graphical elements! That hitches me!

I dislike TUIs because they are sub-optimal versions of GUIs. And here, I think a lot of people make a confusion with UX and UI. A GUI can be beautiful, rich of graphical elements, and have a terrible UX (it’s the case most of the time). People writing GUIs tend to focus on mouse-driven interactions… which doesn’t have to be. So people tend to associate GUIs with mouse-only workflows, while a GUI can completely do everything a TUI does… but it can also do much better.

A couple of arguments against TUIs:

• Graphical elements are faked by using unicode symbols (drawing blocks), which implies having all the elements laid out on a display cell grid. Oftentimes, the unicode symbols will not be correctly aligned, resulting in graphical glitches, or simply ugly pop-ups borders, etc.
• Also, still about unicode glyphs, if the application doesn’t implement it correctly, that text is just “part of the text of the application”, so copy-pasting can be challenging and very boring.
• Since everything has to be put on a display cell grid, you have no way to have pixel-based movements, alignment or anything based on pixel. The smallest unit, the basic primitive, is a unicode character. About that, I think the most interesting “fake” thing is wfxr/minimap.vim, which is a minimap for neovim in a terminal. And you can’t do any better than that, because, well, you can’t go any smaller / different than a glyph.
• Applications run in a terminal, which drives the performance of the TUI application. That results in non-deterministic experiences. Basically, you can write a super great application that will run like an elder snail on some terminal emulators.

Summary of the problems

So let’s do a quick recap of what’s wrong with today terminals:

• TUIs are not rich enough in terms of graphical experience, and everything graphical (splits, lines, pop-ups, etc.) are somehow faked.
• CLI-based composition often ends up being a nightmare of running the same command over and over by adding more piped commands.
• A terminal is a static world, where (besides TUIs) everything is just static text and nothing changes unless you run a command again, wiping the previous result and replacing it with the new one.

Those are the three main pain points I feel about using a terminal. Now, you might already have used something like a monitor application (I work at DataDog, so I’m used to them) or used a web browser or native GUI and see that you can have animations, drop-down lists that actually look good, etc. Putting all that in contrast with terminals makes me a bit sad, especially in 2022.

What would be the (next) perfect productivity platform in 2022?

My latest blog articles are centered around that topic:

• My thoughts about editors in 2020
• My thoughts about editors in (early) 2021

So it’s been an important topic to me lately. I have been thinking about productivity platforms for a while now, and the conclusion I came to is as follows.

The terminal needs to change

Instead of switching to an IDE like IntelliJ or VS Code, I still think we need composition, but not in the form of pipe shells. I think the CLI has to evolve. I have started a project on my spare-time to try and change how programs would work with their environment. See, a shell is basically just a way to call the exec syscall (execve on Linux for instance) and set its arguments, environment and standard input / output (plus all the candies you can get from a shell, such as scripting languages, etc.).

The interpretation of the inputs and outputs of a program is actually completely left to… the running process, which is most of the time the shell for CLI applications. This is why nushell is such an interesting new shell: it can interpret more than just lines of text. And I think we need to move in a direction similar to this.

I think we should see more alternative forms of “terminals”. We could even imagine a program that doesn’t have the concept of “shell” nor “terminal” anymore. It’s easy to imagine having an application that can simply call execve and do whatever it wants the environment, inputs and outputs. It could have some primitives implemented. For instance, imagine that a program could be run in your “new terminal” and output its results in a tree view, while other programs are also running, displaying their own things. You could have a program run without exiting, updating the content of the tree view or even accepting filters, sorts, field extractor or whatever see fit.

Editing needs to come back to editing

Today, text editors are overloaded. Heck, even small editors such as neovim now have a community developing plugins that have nothing to do with editing. For instance, fuzzy searching files or Git management. When you think about it, if the platform (i.e. terminal) had better primitives, it should be possible to compose programs in a way that doesn’t require people to rewrite the same kind of logic (i.e. fuzzy finders) in all the programs they use. fzf is a good example of that, but it’s limited to the CLI (you can still use it in TUI but to me it’s a bit hacky). Terminals should have a primitive to, for instance, run a program in overlay and pass the output to another, running program. That would allow people to write “pure generic fuzzy finders” once and for all, and let people use the editors they like.

Today, all that logic doesn’t really exist outside of individual and scoped efforts. Yes, you can probably find programs supporting that, but they will certainly not run in a terminal and will have their own protocols.

Applications need to compose in a new, modern way

Composing applications with pipes is easy to wrap your fingers around, but it gets limited and limiting as soon as you use something like a GUI. Imagine that programs could speak a common language, based on, for instance, local sockets, to exchange messages in a way that whatever the kind of programs you write, you can still compose them. Composing two GUIs between each other should be something that is widely supported, and standardized.

Something else with piping applications: it’s limited to how we use CLI applications, which is via the command line. Running programs in the command line takes the form of:

program <arg1> <arg2> … | another_program <arg1> <arg2>

This is highly summarized, but you get the idea. CLI programs don’t provide a great discoverability experience, and it’s harder to iterate on them. For instance, in a GUI, if you filter a list with a predicate, it’s super easy to “experiment around” by changing the filter name. In a CLI session with piped programs, you are likely required to use your up arrow on your keyboard (or whatever shortcut) to invoke the last command again, and change the arguments in the middle of the line. While doing this, you will still have to run all intermediary commands, which are going to perform side-effects, etc. etc. And if you want to be smarter and use the > or >> operator to cache the results, then you will still have to remember the name of the file you used, and cat or tee that file again. It gets time to get used to using that, and I truly think that it’s not really worth it, because today I’m 30 and I’ve been developing since I’m 11, and I still don’t really enjoy that kind of process.

Applications need to change

The essence of an application, today, is actually platform-dependent. Heck, it’s even environment dependent. At work, an “application” can be as simple as a small Python script or be a Kubernetes cluster composed of several deployments, stateful sets and DNS rules. However, when we think about applications we use on a daily basis (what people would call “heavy” or “native” applications), they are pretty similar to the following:

• For CLI applications, they are akin to effectful computations. They take inputs (environment, stdin, arguments), they output something (stdout) and they can have side-effects (calling another program, changing shared memory, doing stuff on your file system, various kinds of I/O, etc.).
• For TUI applications, it’s similar but they don’t read from stdin nor output to stdout in a one-shot way. Instead, it’s like an event loop that reads from stdin and a render loop that writes to stdout.
• For GUI, it depends on the platform but most of the time, GUIs will be closer to the hardware, because they are not restricted by the protocol they are written for (i.e. CLIs / TUIs cannot really go any lower stdin and stdout in terms of UX; GUIs can). A GUI application can decide to use OpenGL, Vulkan or something higher such as Gtk, Qt, or a Web kit.

I think that we should change that. Remember that running an application is just a matter of calling execve (or similar on non-Linux), which basically requires a path to the application, the list of arguments (the argv) and the environment (envp). Setting the environment is typically done by the shell (and some variables come from the terminal too), but it could be done completely differently. On the same idea, the argv is filled by the CLI arguments you provide, but they could be computed and filled in a completely different way. And finally, the interpretation of stdout (mostly done by the terminal) could be interpreted in a completely different way as well.

Imagine that we could write to stdout the port / socket on which we would like to open a communication with a new, modern protocol, that would allow us to manipulate a new kind of “terminal.” Instead of using a regular text-based terminal, it would be a piece of software allowing to manipulate pop-ups, text buffers, image / vector image buffers, notification queues, etc. etc.

Obviously, I’m not inventing all that. If you know about emacs, you know that that’s basically what they do, but instead of using stdin, stdout or execve, they just evaluate Elisp. However, what I think could be very interesting would be to allow native applications to do the same thing, with a native platform that would ship without any real applications (so unlike emacs), and let applications implement their own workflow.

That’s basically what I’ve been working on and experimenting lately. A platform that provides buffers, tree views, notifications, pop-pups, overlays, etc. to allow any kind of applications that can read and write to sockets to use those features as if they were native, and platform-independent, in the same way that you use stdout without even thinking how it will be displayed in the terminal.

Leveraging such a platform would solve most of the problems I mentioned above, because:

• We could write a code / text editor that wouldn’t have to be worried about extensions like Git: the Git support would come as a native application (equivalent of the CLI git application) that would open an overlay, for instance. That application wouldn’t even know about the code editor: you would make that connection via the platform.
• Applications could communicate between each other to manipulate buffers, get the contents of the buffer and do various kind of operations on them (LSP servers, for instance).
• Because the protocol would be completely rendering-agnostic, that would allow people to write an application that would work for any kind of “platform implementations.”
• Composition would use the low-level protocol to compose applications. You could imagine supporting an interface between applications allowing to filter the contents of the buffer of one by using another application. Applications such as fzf could branch on the buffers of a text editor, for instance. Or you could even open a buffer in the text editor by running a fuzzy finder as another application. All of that would compose in a seamless way.
• Etc. etc.

Eh, of course, I know that such a platform protocol will probably never appear unless I make it, very opinionated and subject to never be adopted by anyone else but me (or a small group of enthusiasts about that kind of ideas). Maybe this blog article would have given you some ideas or hindsight about your own tools. Or maybe someone knows such a platform (that I don’t) and will make me realize it already exists, or is a work in progress. Maybe, after all, it will just launch a discussion about what developing means in 2022. Because to me, using tools that used to be efficient and proved to be great ones a couple of years ago, doesn’t mean they are still a thing today. And I really mean it, because I’m currently writing this very article in neovim, in a kitty tab among dozens, and I just wish I had the DE I just described above.

Keep the vibe!

Reddit discussion

Kakoune and the shell

Because Kakoune doesn’t have a plugin interface, you are limited to what is called kakspeak, which is basically what you can type in the command line (the : line). Contrary to other editors like Vim, everything you type in that : line can be laid out in a file (a .kak) and be interpreted directly. Another cool aspect about that is that you can just select some part of a .kak file, and simply type :^r.<cr> – in Kakoune, the . is the selection register. That will execute the Kakoune command.

This property is really good, but still, you are limited in what you can do. Among the command you will be running:

• declare-user-mode, to declare your own mode (yes, like insert mode, normal mode, etc.). Yes it’s a default / core feature and yes it’s excellent.
• set-face to declare / update highlighting groups.
• execute-keys and evaluate-commands to execute keys as if the user typed them, in sandboxed / isolated environments. This is incredibly powerful, as you can run some commands that creates, updates registers, move the cursor around, etc. but since it’s sandboxed, as soon as the command is done, you get back to the state you were in before issuing the commands.
• And more.

There is nothing to write plugins… except one thing.

String expansions

Kakoune has this concept of expanding strings. It’s the same feature as in any other editor: some strings can contain special keywords and identifiers to replace their content with what they hold. For instance, in your shell, it’s very likely that this string will contain your username: "$USER", or this will be the current year "$(date +%Y)". However, this will remain verbatim: '$(date +%Y)'. The reason is that, in a shell, " expands while ' doesn’t.

Kakoune has the same mechanism, but the syntax is different, and Kakoune has different source of expansions. For instance, %opt{foo} will be replaced why the foo option, that can be set with set-option. %val{timestamp} contains the current timestamp of the buffer, etc. etc.

There is one interesting expansion that Kakoune has: %sh{}. This is shell expansion. It will execute its content inside a thin shell. For instance, try open Kakoune and enter in the command line, something like :echo %sh{date +%Y}. You can see where we are going here. We can use that to run arbitrary shell commands.

Kakoune is monothreaded, so when you run a command in a shell, it blocks until the shell command finishes. On its own, it’s not that bad. It forces us to call short-living shell commands.

This mechanism allows us to run external programs, but it doesn’t tell us how we can call back Kakoune.

Kakoune and UNIX sockets

Kakoune is monothreaded, but it’s concurrent. It listens on a UNIX socket Kakoune commands that any external programs can send, via the kak -p interface.

I initially tried to send content to the UNIX socket programmatically, but it wasn’t planned for that, and hence hit issues while doing so. It hurts to say that but you have to spawn a programm running kak -p; forget about writing directly into the UNIX socket for now.

So, with this mechanism, we can:

1. Run a short-living program via %sh{} expansion to talk to, for instance, a server, quickly accepting our request and treating asynchronously.
2. Then, once the request is handled, send back the response to Kakoune by running a kak -p program, using the UNIX socket.

The cool thing is that Kakoune follows a server/client architecture and has a session identifier (you must pass it to kak -p). You can retrieve that value with %val{session} — and inside %sh{} expansion, it’s available as an environment variable $kak_session.

And here you have it. The formula I’ve been using successfully to add tree-sitter support to Kakoune. Whenever we need to highlight the buffer again, simply craft a small request to send to the kak-tree-sitter local server and immediately get control back (so that the UI doesn’t freeze). Then, at some point, the highlight request is computed and arrives via kak -p in Kakoune.

But you might have a question… how do I deal with the buffer content? Indeed, the only thing we can do with with %sh{} is starting a program in a shell. We could do something like laying the buffer content on the shell invocation but that’s seriously limiting (especially on giant buffers). We could put the content of the buffer in an environment variable, but it would suffer from the same problem (and damn it’s so dirty). What else?

The final part of the recipe: FIFOs

UNIX systems have this incredible thing called FIFOs. I FIFO — also named pipe — is a special kind of file. It lives on your filesystem (so it’s located at a given path), a bit like UNIX socket. However:

• Its content never exists on the filesystem. It’s all in-memory.
• It’s a streaming primitive, so you cannot just write into it and assume it’s stored somewhere.
• Think of it as a buffer between two entities: a reader and a writer.
• When a reader reads from it, it blocks until data is available to read.
• When a writer writes to it, it blocks until a reader is available to read.

So it implements a rendez-vous buffer between a single reader and a single writer. And yes, the | in your shell is using something that behind the scene. The thing is: you can create your own, and you don’t even need to write any code. Enter the mkfifo program. For instance, you can try it out on your own by creating a FIFO (let’s call it rdv), reading its content with cat first (you’ll see the cat process freeze, so you will need another terminal session!) and then write content to it, for instance with echo:

mkfifo /tmp/rdv

# in shell 1
cat /tmp/rdv

# in shell 2
echo "Hello, world!" > /tmp/rdv

As seen as the echo starts writing, you can see cat return the result.

Now replace cat with tail -f 😏.

Anyway, Kakoune has a mechanism where it scans %sh{} blocks and it sees $kak_command_fifo and/or $kak_response_fifo, it will create those FIFOs for us (and manage their lifetimes). Because we are in the shell, we can write Kakoune commands to execute in $kak_command_fifo, which will be executed as soon as you’re done writing to the FIFO, and you can read $kak_response_fifo from, for instance, an external program, to get more data from Kakoune.

This is the exact mechanism that is used to stream buffer content between Kakoune and kak-tree-sitter. Here’s the Kakoune commands used to highlight a buffer:

# Send a single request to highlight the current buffer.
define-command kak-tree-sitter-highlight-buffer -docstring 'Highlight the current buffer' %{
  nop %sh{
    echo "evaluate-commands -no-hooks -verbatim write $kak_response_fifo" > $kak_command_fifo
    kak-tree-sitter -s $kak_session -c $kak_client -r "{\"type\":\"highlight\",\"buffer\":\"$kak_bufname\",\"lang\":\"$kak_opt_filetype\",\"timestamp\":$kak_timestamp,\"payload\":\"$kak_response_fifo\"}"
  }
}

I won’t explain the protocol into two much details, but the important part is that I start a shell to run kak-tree-sitter … -r, format the request (it’s just plain JSON), and ask kak-tree-sitter -r to read from $kak_response_fifo. You can see in the previous line that we write to it (the write $kak_response_fifo basically means to write the content of the current buffer to $kak_response_fifo, which is a file — everything is a file in UNIX!).

kak-tree-sitter -r is made in a way so that it exits quickly. It will read from the FIFO file and forward the request to the kak-tree-sitter server, which, in turn, will move the request to a different thread so that it can quickly mark the request done. The whole thing is then synchronous, but extremely fast. The only bottleneck we have here (and mind it, it’s important) is that we must read from the FIFO synchronously in the shell kak-tree-sitter -r.

How’s it going?

I’ve been running with this setup for weeks now, since I started kak-tree-sitter around the end of April, 2023. The code you read above runs in a couple of Kakoune hooks (the same kak-lsp is using or very similar), which waits for a idle time after the buffer is edited (in practice, 50ms after the last edit operation). And it’s already fast enough.

However, there is a nice optimization that we could do here. See, the only reason to start a shell is to format the request to send to kak-tree-sitter, the server. We can completely by-pass it. Instead, we could:

• Create the FIFO in kak-tree-sitter, when a new Kakoune session is created.
• Write the requests to the FIFO handled by kak-tree-sitter. No shell is needed to write to files!
• The rest is the same, since the server sends back highlighting Kakoune commands via kak -p.

This on its own should greatly enhance performance, which is already pretty good, even with the shell. I plan on working on this enhancement in the upcoming days.

Alright, but what’s wrong then?

Well, there is one thing. See, in order to support tree-sitter, I had to write this kak-tree-sitter server, and write buffer contents to FIFO files. kak-lsp is doing the same. All of that is synchronous, and even if it’s fast, it’s still two sequential locks of the buffer, copy of the buffer, etc. On my side, I’m currently exploring the %val{history} expanded variable, which contains the textedit operations (so that I don’t have to stream a full buffer and diff in kak-tree-sitter anymore, but instead just small chunks of updates).

However, the problem still holds. The design of Kakoune is nice when you’re working alone with your small integration, but when you have two big ones (LSP and tree-sitter are not small environments), I think Kakoune shows its limit.

We – @krobelus and I – discussed that matter. A middleware program or a change in how Kakoune interfaces with external programs, especially for buffer streaming, would be greatly appreciated. But it’s not currently the case. And even if we decide to come up with a middleware – that could act as a buffer cache / map, for instance – we would still be writing buffer contents to different FIFOs.

Another thing that I’ve been thinking about a lot is… is this the right approach? Something like tree-sitter seems to be ideal as an embedded library, directly inside the code of your editor. Especially since Kakoune is all about selections, being able to have semantic selections by default seems like something pretty good. tree-sitter requires some runtime resources (relocatable objects like .so / .dylib, queries, etc.)… and it’s the same thing with the regular Kakoune highlighters (by default, Kakoune doesn’t have any; they come bundled up with your distribution).

I’m not entirely sure the approach scales very well. Of course, I still think the design is excellent, and it prevents too much maintenance on Kakoune, which is also a good thing. For instance, this runtime resource problem is something I’m solving in kak-tree-sitter (and easing with a controller tool called ktsctl, which can download, compile and install grammars and queries for you), but still. The current version of kak-tree-sitter only supports semantic highlighting, not text-objects just yet (but it shouldn’t be too hard to add). The state of the project is not completly ready for people to jump in (the wiki is not written), but if you tag along on Matrix, I can help you get started.

Please consider kak-tree-sitter as an experimental project, because I’m not sure this is the right approach, even though it’s probably the only one for Kakoune for now (I don’t think @mawww plans on integrating it into the core of Kakoune).

Keep the vibes!

Most of the time, if you are a CLI/TUI enjoyer, you will likely have a similar workflow to this:

• ls to show the directories. You will locate the first directory you want to go to.
• cd <that-dir>.
• ls again to show what’s there.
• cd <another-dir>.
• Repeat until you are at the place you want.

I don’t think I need to debate on the fact that this is a very time-wasting workflow, and honestly not very pleasant. Most shells today allow you to do something like cd <tab> and have a way to virtually visit the directories, until you find the one you want. Press <return> and your command is completed. You can use the same method for tar-ing files, removing files, running arbitrary commands, etc.

Another interesting way of doing that is to use a fuzzy finder, like fzf or skim. I would usually just do cd ^t. That works when you know exactly what you are looking for, which is not exactly the situations we are talking about here.

The cd example is what motivated me to make a small tool that I named flirt, but along the way, I realized it could do much more interesting things, without expanding its scope and not violating the UNIX philosophy.

FiLe InteRacT, the file interaction tool for your CLI

I never liked file browsers, like nnn, lf or yazi. They look cool, but there is something too much about them. I like the Kakoune’s way. I think the UI from file browsers is interesting, but I think we could use it in a much more barebone/simple (and UNIX) way. The idea is to use it as a read-only UI, and let other tools compose around it.

For instance, let’s take the cd example from before, where we go to a directory by interleaving cd and ls commands. What do we want to actually do?

1. Locate a directory.
2. cd into it.

flirt allows to implement the first part. You can do something like cd $(flirt) — or cd ^s for a shell shortcut integration, which I highly recommend — and move around directories until you have found the one you are interested in. Quit flirt, and you have your CLI set to cd <path>. Just press <return> to jump to that directory.

This is a simple workflow, because it allows you to think of flirt just as a read-only view into your filesystem. But it can do much more.

Arbitrary files selection and reordering

flirt can select multiple files. Why would you want to select many files? Well, imagine that you want to select a bunch of files and put them in a directory. It’s a pretty cumbersome operation to do manually on the CLI, because you have to type a lot of text to just pick the files you want to feed your mv command. With flirt, you can do something like mv ^s and pick the files you want.

Because flirt is ordered — you can see the order on the right-side view and switch between the left and right views with the <tab> key by default — you can ensure the destination directory is the last argument — interactively.

Unlocking the full potential with other UNIX tools

Have you heard about moreutils? It’s a collection of UNIX tools that go a bit further in terms of composability. One of those tools, vipe, is a pipe editor: it reads from stdin and pipes its content to your $EDITOR. Once you have finished editing your buffer and quit your editor, it will pipe the modified data back into its stdout:

cmd1 | vipe | cmd2

Composing with flirt is super easy and you can implement interesting workflows, such as with:

flirt | vipe | sh

Which allows you to select a bunch of files on which operate commands — that you add in your editor, via vipe — and execute the output script!

If you are interested, you can find flirt here, along with some additional links:

• Discussion mailing list
• Development mailing list (send your patches here!)
• Feature requests / bug reports

If you have cargo installed, you can install flirt easily:

cargo install flirt

I might add a PKGBUILD for Archlinux at some point.

Do not hesitate to send your feedback on the discussion mailing list! Keep the vibes!

This blog post sums up what I did with AoC#18, my thoughts about the puzzles and even a meta-discussion about programming challenges. I used Haskell for most challenges and switched to Rust for no specific reason. Just fun.

Also, because the puzzles’ texts are somewhat long, I will just give a link to the text instead of copying it and will just make a very short description of the problem each time.

Finally, don’t expect to find all the puzzles: I stopped at day 15. I will explain the reasons why at the end of this article. My adventure can be found here. Most puzzles have input data. You will find them in day directories as input.txt files.

Enjoy the reading!

If you want to try and take the challenges, I advise you not to read any further as this article would spoil you solutions! You will need a Github account and… a lot of time.

• Day 1: Chronal Calibration
  • Part 1
  • Part 2
• Day 2: Inventory Management System
  • Part 1
  • Part 2
• Day 3: No Matter How You Slice It
  • Part 1
  • Part 2
• Day 4: Repose Record
  • Part 1
  • Part 2
• Day 5: Alchemical Reduction
  • Part 1
  • Part 2
• Day 6: Chronal Coordinates
  • Part 1
  • Part 2
• Day 7: The Sum of Its Parts
  • Part 1
  • Part 2
• Day 8: Memory Maneuver
  • Part 1
  • Part 2
• Day 9: Marble Mania
  • Part 1 & 2
• Day 10: The Stars Align
  • Part 1
  • Part 2
• Day 11: Chronal Charge
  • Part 1
  • Part 2
• Day 12: Subterranean Sustainability
  • Part 1
  • Part 2
• Day 13: Mine Cart Madness
  • Part 1
  • Part 2
• Day 14: Chocolate Charts
  • Part 1
  • Part 2
• Day 15: Beverage Bandits
  • Part 1
• Conclusion

Day 1: Chronal Calibration

Text

Part 1

This puzzle is about summing arrays and finding duplicates (without counting).

First puzzle I discovered and first AoC challenge I ever took, I was surprised at the simplicity. Basically, given lines containing a single number preceded by either + or -, we must compute the sum of all the numbers.

The first thing to do is to parse the file into a stream of numbers. In Haskell, this was almost a one liner:

main :: IO ()
main = do
    numbers <- fmap (map parse . lines) getContents
  where
    parse ('+':xs) = read xs -- (1)
    parse n = read n

If I removed the + from the file, I could even have gone with a one liner:

    numbers <- fmap (map read . lines) getContents

The read function is not safe and I don’t recommend using it for real, production projects. In the context of this challenge, though, it was alright.

I don’t have much to say about this puzzle as I found it not very interesting.

Part 2

We just want to get the first cumulative sum that appears twice. That is, each time a new number is summed, we get a given “current sum”. We add positive and negative integers, so we might end up, at some time, with the same number. Because we don’t know when that will happen, we need to turn the input stream into an infinite stream of numbers that repeat over and over. Haskell has the cycle function that does exactly that: it takes a list and makes it repeat infinitely.

What is great about cycle in Haskell is that it could be implemented in a very naive way and yet yield good performance – thanks GHC!:

cycle :: [a] -> [a]
cycle x = let x' = x ++ x' in x'

Or, prefered (personal opinon):

cycle :: [a] -> [a]
cycle = fix . (++)

fix is a very powerful function any Haskell should know. Typically, when you want to corecursively build something, it’s very likely you’ll need fix. I advise you to have a look at my netwire tutorial in which I used fix pretty much everywhere.

There are several ways to fix this problem. I chose to use a set to hold all the known intermediate sums. Because we’re working with integers, the Haskell IntSet type is perfect for that. The algorithm is then just a special fold over an infinite list that stops when a sum is seen twice by looking it up in the integer set:

findFreq _ freq [] = freq -- this shouldn’t ever happen since the list is infinite
findFreq knownFreq freq (change:xs)
    | newFreq `member` knownFreq = newFreq
    | otherwise = findFreq (insert newFreq knownFreq) newFreq xs
  where
    newFreq = freq + change

Haskell solution

Day 2: Inventory Management System

Text

Part 1

This puzzle requires you to recognize and count characters in strings. For each string, you must check whether they have any letter that appears exactly once and any letter that appears exactly three times. Adding those counts provides a checksum for a list of strings.

I did that in Haskell as well. My idea was to use a count-array of size 26 (since the strings are only in [a-z]. So the first part of my algorithm is to count, for a given string, the number of time each letter occurs. This is done really easily with a fold that increments the proper value value in the array at the index representing the character folded on in the string. That index is obtained by turning a character into a numerical representation and subtracting it the numerical value of 'a':

treatHash :: (Natural, Natural) -> String -> (Natural, Natural)
treatHash occurs hash =
    let result :: State = foldl' replace initialState hash
    in addPair occurs (foldl' incrOccur (0, 0) result)
  where
    replace st l = accum (+) st [(ord l - ord 'a', 1)]
    incrOccur i@(twos, threes) x
      | x == 2 = (1, threes)
      | x == 3 = (twos, 1)
      | otherwise = i
addPair (a, b) (c, d) = (a + c, b + d)

The replace function performs the update in an input vector (point-free function). This will effectively increment the vector’s value at index 3 if the character is d (because ord 'd' - ord 'a' = 3. incrOccur, here, is used to fold over the resulting array (Vector) and compute if a letter appears twice and if a letter appears three times. You will notice that this function doesn’t sum. For instance, if you have aabb, you get no letter that appears three times but you have two that appear exactly twice. However, incrOccur will give you (1, 0), because the puzzle states it should be done this way. Finally, addPair add the number of twos and threes to a pre-defined input – that will be handy for an outer fold.

The algorithm is then run on the input and we get the final result:

hashes <- fmap lines getContents
let checksum = uncurry (*) $ foldl' treatHash (0, 0) hashes

We transform the standard input into lines – i.e. [String] – and then fold them with our treatHash function. Finally, uncurry (*) is a little oneliner to simply multiply the left part of a pair with its right part.

Part 2

This part is about finding strings that are almost the same and differ and only by one letter. As doing a programming challenge, the first thing I want to find is a solution, not the best solution. I also think people should really learn from this:

1. Make it work.
2. Make it clean.
3. Make it fast.

Especially on programming challenges, you’ll be very, very unlikely to implement anything more than (1.), because the inputs are often two small to really benefit from a real optimization. Your time is a real important resource, don’t waste it. Measure whether you really need an optimization. I’m not saying that you should be doing something bad because it’s easier. I’m saying that if it takes you N minutes to write a solution that runs in M milliseconds, if you know that you could do it in, for instance, 10N minutes to write a solution that runs in only 0,7M milliseconds for the foreseen milliseconds, will, you’re going to waste your time.

So, in my case, I started with a naive approach that runs in O(N²): comparing all strings to all others:

searchCommon :: [String] -> String
searchCommon [] = "" -- the empty list has nothing in common
searchCommon (h:hs) = search h hs -- for each string, search in all remaining
  where
    search h [] = searchCommon hs -- exhausted,  search with the next string
    search h (x:xs)
      | almostSame h x = commonLetters h x -- grab the common letters if almost the same
      | otherwise = search h xs -- if not, just try the next string in the sub-list

The algorithm is pretty straight-forward. The searchCommon and search functions are mutually recursive functions that go from, respectively, the whole list of strings to test and the local tail as we advance. almostSame is defined as follows:

almostSame :: String -> String -> Bool
almostSame = go 0
  where
    go diffNb (l:ls) (r:rs)
      | diffNb > 1 = False
      | l /= r = go (succ diffNb) ls rs
      | otherwise = go diffNb ls rs
    go diffNb _ _ = diffNb == 1

This function is a special zip that short-circuits if it knows there are two many differences. When both the input strings are exhausted, if diffNb == 1, then only one character has changed, so the the overwhole function evaluates to True.

The final part we need is commonLetters, that is pretty straight-forward, too:

commonLetters :: String -> String -> String
commonLetters (l:ls) (r:rs)
  | l == r = l : commonLetters ls rs
  | otherwise = ls -- all the rest is identic, smartass

We construct a list that has the same characters as the input lists as long as they’re equal. As soon as they differ, we discard the character and just return any of the input lists – they’re equal. This function only works, obviously, if both the input strings are almost identical (only one character differs and they have the same length). The otherwise branch is a short-circuit optimization that prevents us from traversing the whole inputs after the difference.

Haskell solution

Day 3: No Matter How You Slice It

Text

Part 1

This problem was the first “challenging” as it required more thinking. The idea is that a very large area – the text gives us the hint it is at least 1000 inches on each side but truly, we do not need this information – must be sliced into several rectangular smaller areas (with edges aligned with X and Y axis). Obviously, some rectangular area might overlap and the aim of the first part of this problem is to find out the total overlapping area.

My idea was simple: we can trick and change the problem by discretizing it. This is something I have said already but most of AoC problems have hidden properties and hidden hints. By thinking more about the form of the solution, the area to find is expressed in inches². The rectangular areas are all lying on a 2D grid (1000×1000 at least, remember?) and their coordinates are always natural numbers (they belong to [0;+∞]). Then, my idea was to state that 1 inch² is actually a single “cell” at any coordinate in that grid – imagine that as a pixel. 4 inches² would be a 2×2 region in that grad (yielding 4 cells).

So instead of using the general idea of an area (M×N for a rectangle which sides are M and N long wide), we can simply break a rectangular area into its most atomic components (1×1 cells)… and sum them up! We will effectively end up with the area of this area.

A more interesting property of my way of solving it: we can now have a big array mapping to each 1×1 cell the number of times a rectangle lies on it. When iterating through all the rectangles, we just break them into a list of 1×1 cells, look ingg up and updating the big count array. Once we’re done, we just have to filter that big array to remove any element which count is less or equal to 1. The remaining elements are 1×1 cells that contain at least two overlapping rectangles – we don’t really care about the number. We don’t actually care about those elements: the length of that filtered array is the area we are looking for, because it is the sum of 1×1 elements!

Converting a rectangular area – called claim in the text – into 1×1 cells is very easy in Haskell:

type Plan = Map (Int, Int) Natural -- the big array I told you
type Claim = (Id, Pos, Area)
type Id = Text -- the “name” of the fabric the rectangular area is about
type Pos = (Int, Int)
type Area = (Int, Int)

claim1x1 :: Claim -> [Pos]
claim1x1 (_, (line, row), (width, height)) =
  [(x, y) | x <- [line .. line + width - 1], y <- [row .. row + height - 1]]

As you can see, I chose to use a Map (Int, Int) Natural instead of an array to store the number of overlaps per 1×1 cell. That enables us not to care at all about the size of the grid (remember when I told you we don’t need the 1000 hint?).

The function that updates the Plan to take a claim into account is:

checkClaims :: [Claim] -> Plan
checkClaims = foldl' (\p (x, y) -> checkInch x y p) mempty . concatMap claim1x1

checkInch :: Int
          -> Int
          -> Plan
          -> Plan
checkInch line row = insertWith (+) (line, row) 1

Given a list of claims ([Claim]), checkClaims maps the claim1x1 function and concats the result, yielding a [Pos] list. That list is then folded over with the checkInch x y p function, that takes an empty map as initial value. checkInch just increment the value found in the map if it already exists; otherwise, it sets that value to 1.

Finally, we need to compute the area:

overlappingInches :: Plan -> Int
overlappingInches = length . M.filter (> 1)

As I told you, that is crystal clear: it’s just the length of the filtered map.

Part 2

This part is interesting also: you need to find out the Id of the claim that doesn’t overlap with any other claim. I will not go into too much details about the algorithm as it’s very similar to the previous one: instead of storing the number of overlaps by 1×1 cell, we store a Set Id, giving all claims that are overlapping – we can see that as a more general form of the first part. We also need a Map Id Natural that maps a fabric and the number of times it overlaps another. The fabric that doesn’t overlap any other is then easily identifiable within that map: it has its associated value set to 0:

searchNonOverlapped :: [Claim] -> Maybe Id
searchNonOverlapped claims =
    case M.toList filtered of
      [(i, _)] -> Just i -- the text supposes there’s only one
      _ -> Nothing
  where
    (_, overlapped) = indexClaims claims
    filtered = M.filter (== 0) overlapped -- hello

Haskell solution

Day 4: Repose Record

Text

Part 1

Aaaah, day 4… I really don’t get why I got so annoyed by this one. It is quite simple in theory. But that made me realize something I don’t really like about AoC: the hidden rules. You will see, if you read this whole article, that some puzzles require you to make very important assumptions about the input – and there’re a lot of assumptions you could make, so you have to make the right ones!

This puzzle is about guards that must protect a prototype manufacturing lab. You are given an unordered list of events that occur about the guards:

• When they begin their shifts (you are given the ID of the guard here).
• When they fall asleep.
• When they wake up.
• Each action gives you a timestamp so that you can re-create the historical events.

The goal of the part 1 is to find the guard that has the most minutes asleep, and especially, find the minute it is asleep the most – we must multiply the ID of the guard by the minute.

Obviously, the first part of this puzzle is to re-order the input to have it chronologically. Here is the setup code:

data Entry = Entry {
    timestamp :: LocalTime,
    action :: Text
  } deriving (Show)

type GuardianId = Natural

data Action
  = BeginShift GuardianId
  | WakeUp
  | FallAsleep
    deriving (Eq, Ord, Show)

entryFromString :: Text -> Maybe Entry
entryFromString s = case split (== ']') s of
    [timestamp, action] -> Just $ Entry (parse . unpack $ T.drop 1 timestamp) action
    _ -> Nothing
  where
    parse = parseTimeOrError False defaultTimeLocale "%Y-%-m-%-d %H:%M"

The parsing part is not really interesting as it’s just challenge code: nasty but working parsing code. :D

I then re-ordered the input with:

entries <- fmap (fromJust . traverse entryFromString . T.lines) T.getContents
let byTimeSorted = sortBy (comparing timestamp) entries

By the way, that code made me want to tweet about how Haskell is actually pretty easy to read and reason about. Anyway.

The next part of the algorithm is to transform the entries into a list of timed action. I actually decided to stream it so that I could benefit from Haskell’s stream fusion – and because it’s so simple and transparent:

readGuardianId :: Text -> Natural
readGuardianId = readT . T.drop 1

treatEntries :: [Entry] -> [(LocalTime, Action)]
treatEntries = map $ \entry ->
  let time = timestamp entry
  in case T.words (action entry) of
    ["Guard", ident, "begins", "shift"] -> (time, BeginShift $ readGuardianId ident)
    ("falls":_) -> (time, FallAsleep)
    ("wakes":_) -> (time, WakeUp)
    _ -> error "lol"

That is like mixing streaming and parsing at the same time. Then, the core of my algorithm: dispatch the actions by guard. That is mandatory if we want to actually accumulate the “state” of a guardian (when they’re sleeping, waking up, etc.). Otherwise, we get interleaved results.

dispatchActions :: [(LocalTime, Action)] -> Map GuardianId [(LocalTime, Action)]
dispatchActions = go mempty Nothing
  where
    go guardians _ ((t, action@(BeginShift gid)):xs) =
      go (insertAction gid t action guardians) (Just gid) xs

    go guardians jgid@(Just gid) ((t, action):xs) = go (insertAction gid t action guardians) jgid xs

    go guardians _ [] = fmap V.toList guardians

    go _ _ _ = error "dispatchActions: the impossible fucking occurred!"

    insertAction gid t action guardians =
      M.insertWith (flip (<>)) gid (V.singleton (t, action)) guardians

This is a by-hand fold that just applies the rule of beginning a shift (storing the ID of the guardian that went napping so that we can correctly dispatch the remaining events).

Then the tricky part:

type Minute = Natural
type Minutes = [Minute]

minutesCounts :: [(LocalTime, Action)] -> Minutes
minutesCounts = go zeroMinutes Nothing
  where
    zeroMinutes = replicate 60 0 -- (1)
    asMinutes = todMin . localTimeOfDay

    -- the guard was sleeping
    go minutes (Just sleepTime) ((t, action):xs) =
      case action of
        BeginShift _ -> go minutes Nothing xs
        FallAsleep -> go minutes (Just t) xs -- not sure if that would even occur in the input
        WakeUp -> go (addSleepCount minutes (asMinutes sleepTime) (asMinutes t)) Nothing xs

    -- the guard was awake, so we’re only interested in when they go to sleep
    go minutes Nothing ((t, action):xs) =
      case action of
        FallAsleep -> go minutes (Just t) xs
        _ -> go minutes Nothing xs

    go minutes _ [] = minutes

    addSleepCount minutes sleepTime t = zipWith (+) minutes range -- (2)
      where
        -- this function is a bit hacky but it generates, for a given range of time, a list of 60
        -- elements where the time period has 1 and all the other has 0 (I leave you to the
        -- exercise of making that a better function)
        range :: Minutes
        range = replicate sleepTime 0 <> replicate (fromIntegral t - sleepTime) 1 <> replicate (60 - t) 0

This big function generates a list which length is 60 – mapping the number of times a guard has passed sleeping at a given minute from midnight to 1:00 AM (see (1) and (2)).

Finally, what we need is a way to compute frequencies – or counts. That is, given a list of anyting, compute that number of time a given anything happens in the list. I wrote a small utility function for that – I got inspired by [@jle], thanks!:

freqTable :: (Ord a) => [a] -> Map a Count
freqTable = M.fromListWith (+) . map (,1)

Then, finding the guard that has slept the more and the minute is easy:

findMostOccurring :: Map a Count -> (a, Count)
findMostOccurring = maximumBy (comparing snd) . M.toList -- and Haskell is hard?! ;)

findSleepiest :: Map GuardianId [(LocalTime, Action)] -> (GuardianId, (Minute, Count))
findSleepiest =
    fmap (findMostOccurring . freqTable . spanIndex) . maximumBy (comparing $ sum . snd) . M.toList . fmap minutesCounts
  where
    spanIndex = concatMap (\(i, x) -> replicate (fromIntegral x) i) . zip [0..]

We first find the guard that has the most time asleep (maximumBy (comparing $ sum . snd). Then, we find the minutes at which they were asleep the most (findMostOccurring). We are given the guard ID, the given minute and the number of times they were asleep at that minute. Yay!

Part 2

For this part, we would like to know which guard is most frequently asleep on the same minute? We already have written all the code needed for that:

findMostFrequentlySleepy :: Map GuardianId [(LocalTime, Action)] -> (GuardianId, Minute)
findMostFrequentlySleepy =
    fmap findMin . maximumBy (comparing $ maximum . snd) . M.toList . fmap minutesCounts
  where
    findMin = fst . maximumBy (comparing snd) . zip [0..]

Instead of summing, we find the maximum time a guard was asleep. Pretty easy.

Haskell solution

Day 5: Alchemical Reduction

Text

Part 1

That puzzle is very natural to solve in Haskell. You are given an ASCII string that contains only letters (lower case and upper case) that represent polymers. You must compute their final reduction by following some basic rules:

• Two adjacent letters will cancel them out if they don’t have the same case (lower vs. upper) but are the same letter. For instance, aA and Bb cancel each other but not aa nor BB.
• This rule happens until no more reduction is possible. For instance, AbBa will first get reduced to Aa because aB will cancel out, but then Aa will also cancel out and we will be left with nothing.

You must give the number of units left in the final reducted polymer after all reductions have occurred.

As I said, that is very simple and elegant in Haskell:

reduce :: String -> String
reduce = go []
  where
    go [] (x:xs) = go [x] xs
    go a [] = a
    go (a:xs) (b:bs)
      | not (isLetter b) = go (a:xs) bs
      | (toLower a /= toLower b) || (isLower a && isLower b) || (isUpper a && isUpper b) = go (b:a:xs) bs
      | otherwise = go xs bs

I decided to use a zipper-like traversal. My idea is the following:

• Read a character. If we have nothing previously seen, just place it in the previous list.
• If we have something previously seen, check whether it reacts with the last previously seen character. If so, just drop it and drop the previously seen character, and go on with the next character.
• When we have exhausted the input list, the previously seen list of characters is the final form of the reduction.

This algorithm allows me to reduce by doing a forwards-and-backwards kind of sweeping, yielding nice performance. Also, notice that the resulting list is reversed because of how we accumulate the seen characters. Because we don’t care about the order, we will not reverse it back to its original order.

The result is just the length of the output list.

Part 2

This part asks us to find the polymer that is the smaller if we remove one kind of unit (a single letter type). So if we remove a for instance, we must remove all a and A.

As there’re only 26 possible solutions (from a to z), and because my solution to part 1 was already fast, I decided to go brute-force with this one: reducing the input string without a’s, reducing the input string without b’s, reducing without c’s, etc. And then simply take the shorter one.

bruteForce :: String -> Int
bruteForce polymers = minimum (map length allReduced)
  where
    types = ['a' .. 'z']
    allReduced = map (\c -> reduce $ filter (\x -> toLower x /= c) polymers) types

Winner winner chicken dinner.

Haskell solution

Day 6: Chronal Coordinates

Text

Part 1

That puzzle was one of the funniest I did. The idea is that, given an infinite 2D map, you are given a list of several points of interest (POIs) in the form of (x, y) coordinates. The goal, for this first part, is to find the largest zone in which all points have the same POI. What it means is that, given several POIs, every positions on the map has a nearest POI (it can have several if it’s at equal distance to several POIs – those must be discarded by the algorithm so that they do not count into any zone). Several positions with the same nearest POI and adjacent to each others form a zone, so that anyone in that zone knows that the nearest POI is the same accross all spanning positions of the zone – you can picture the zone easily as discs centered on the POIs, but deformed by other POIs.

The tricky part is that the map is infinite and POIs are scattered around it.

My idea was based on something I do a lot on my spare time with my 3D projects: compute AABBs. An AABB is an enclosing box in which all points lie. The idea is that its size must be as minimal as possible. An AABB, which stands for Axis-Aligned Bounding Box, is the minimal bounding volume that enclose a set of points and which has its edged aligned with the axis (in our case, the X and Y axis). By the way, an AABB in 2D is also called MBR, which stands for Minimum Bounding Rectangle. I chose AABB instead of MBR because I’m more used to work in 3D, but they’re essentially the same thing.

So, the first thing I wanted to do is to compute the AABB of all the POIs for a two reasons:

• The most important one: it helped me reduce the problem space from an infinite space to a finite one: instead of having an infinite 2D map, I now have a finite rectangular 2D region to explore. Which is, you’ll have to admit, much more comfortable. ;)
• If you read the puzzle’s text, you’ll have notice this:
  • “Your goal is to find the size of the largest area that isn’t infinite.”
  • What it means is that all the points outside of the AABB are in an area that is always infinite, so we will never be interested in those zones.

Ok, let’s see my code:

type Point = (Int, Int)

-- Note to readers: this the way I like to encode AABB because it eases some operations on points.
-- The lower point is a point that belongs to the AABB that satisfies the rule that no other point
-- with different coordinate are lower than it. Same thing for upper. I also like that encoding
-- because generating an AABB from a set of points is trivial.
data AABB = AABB {
    aabbLower :: Point,
    aabbUpper :: Point
  } deriving (Eq, Show)

findAABB :: [Point] -> AABB
findAABB [] = error "nein" -- this will never be called, so we don’t care about type safety here
findAABB (a:ls) = foldl' updateAABB (AABB a a) ls
  where
    updateAABB (AABB (lx, ly) (ux, uy)) (x, y) = AABB {
        aabbLower = (min (min lx x) lx, min (min ly y) ly),
        aabbUpper = (max (max ux x) ux, max (max uy y) uy)
      }

-- This function gives me a list of points that are in the AABB. It actually gives me all the points
-- the AABB wraps.
aabbToStream :: AABB -> [Point]
aabbToStream (AABB (lx, ly) (ux, uy)) = [(x, y) | x <- [lx .. ux], y <- [ly .. uy]]

-- Test whether a point lies on any edges of the AABB. You’ll get why this function is important
-- later.
liesOnAABB :: Point -> AABB -> Bool
liesOnAABB (x, y) (AABB (lx, ly) (ux, uy)) = x == lx || x == ux || y == ly || y == uy

I annotated the code with comments so that you can get what it’s for.

So, I create the AABB and then I call aabbToStream in order to get all points. You might already have guessed the next step: we are going to find the nearest POI to all the points. For this, I just went naive and just computed the Manhattan distance to all POI and kept the smallest. If we map that function to all coordinates generated by the AABB, we get the first part of the solution.

manhDist :: Point -> Point -> Int
manhDist (a, b) (c, d) = abs (a - c) + abs (b - d)

nearest :: Point -> [(Int, Point)] -> Maybe Int
nearest p points =
  case sortBy (comparing snd) $ map (\(i, x) -> (i, manhDist p x)) points of
    [a] -> Just (fst a)
    a:b:_ -> if snd a == snd b then Nothing else Just (fst a) -- (1)
    _ -> error "nearest"

Here, (1) applies the rule I described earlier about at least two POIs at the same distance: we just discard the point and it doesn’t participate in creating any zone.

Then, how do we find the biggest area? Easy: we re-use our freqTable function from Day 4 to compute a frequency table! In my case, I just renamed that function freqs:

freqs :: (Ord a) => [a] -> Map a Natural
freqs = fromListWith (+) . map (,1)

If we call that function on a list of [Int], we end up with Map (Maybe Int) Natural that gives us the number of positions a given POI is the nearest. It’s perfect, because it’s exactly what we are looking for!

biggestArea :: [Maybe Int] -> Natural
biggestArea = snd . maximumBy (comparing snd) . M.toList . freqs . catMaybes

Here, catMaybes just remove the Nothing case so that we go from [Maybe Int] to [Int]. We then find out which POI has the biggest number of nearest positions and we simply return it. Because those are positions, their sum is then the area of the zone: we’re done. Or almost. Remember that some zones have an infinite areas. Thanks to the AABB, it’s actually easy to find which ones: those have at least one point that lies on the AABB’s edges. We just have to iterate through all the points and black list some points:

blackListPoints :: [(Point, Maybe Int)] -> AABB -> Set Int
blackListPoints points aabb = foldl' blacklist mempty points
  where
    blacklist blist (p, Just i) = if liesOnAABB p aabb then S.insert i blist else blist
blacklist blist _ = blist

Part 2

The part 2 asks something different: now we want to find the area of the region containing all locations for which the total distance to all POI is less than a given constant (10000). My solution was actually way easier than expected, surprisingly:

safeArea = filter (\p -> sum (map (manhDist p) coords) <= 10000) points

Done. :)

Haskell solution

Day 7: The Sum of Its Parts

Text

Part 1

Here we go again: graph theory. Fortunately for us, it’s not a hard graph puzzle. That first part is to simply display a string that shows the order in which a graph must be traversed. If two nodes can be traversed at the same time, the node which letter comes first alphabetically is traversed first.

I’ll just show the traversal because the rest is not really interesting for that puzzle:

-- The graph encodes the relationship in reverse: it maps each node its list of dependencies.
-- So if we have something like A -> [], it means that the A node doesn’t have any dependency.
type Graph = Map Step (Set Step)
type Step = Char

-- Get the list of all available steps; i.e. they don’t have any dependency.
getAvailable :: Graph -> [Step]
getAvailable gr = [step | (step, set) <- M.toList gr, S.null set]

-- Traverse the graph and get the ordered steps to go through.
stepAvailable :: Graph -> [Step]
stepAvailable gr = case sort (getAvailable gr) of
  [] -> []
  (s:sx) -> s : stepAvailable (removeStep s gr)

removeStep :: Step -> Graph -> Graph
removeStep s = purgeDep s . M.delete s
  where
    purgeDep = fmap . S.delete

It’s a typical functional problem that gets solved very easily in Haskell.

Part 2

The second part is pretty interesting. Instead of stepping through all the steps sequentially, you ar given a pool of workers. It will take a given amount of time for a given worker to complete a task and able us to visit a given node in the graph. We have to guess how many time it will take to complete all of the steps.

I won’t post the code (it’s on GitHub if you want to have a look at it) as it’s a bit boring and the idea of my solution is enough. The concept is to have a stepped simulation (i.e. you perform a set of action in a given “round”, then repeat). In my case, each round is composed of several steps:

1. First, partition the current work load into a set of done tasks and running tasks. This is quite easy to do by just checking at the remaining time of each task. If the remaining time is 0, then it’s done, otherwise it’s still running.
2. Generate the time increment. This is the minimal duration until a next interesting action occurs (i.e. a task gets done). Nothing can happen below that duration. That value can easily be found by looking up the remaining duration of the running tasks and taking the minimum.
3. If we still have running tasks, step forward (i.e. recursively call the same function) by advancing the current time by the time increment and removing the done tasks.
4. The backlog, that is implicit, can be created by monoidal operations and is detailed in the code on GitHub.
5. When the backlog gets empty, we have the final time and the answer to the initial question.

This part was interesting because it made me write a parallel graph traversal (a graph task scheduler) that could be used as base for a real and parallelized (I/O) task scheduler. Interesting stuff.

Haskell solution

Day 8: Memory Maneuver

Text

Part 1

In its simple form, this puzzle is not really interesting and I could definitely present you the solution in a single paragraph. However, I found it pretty fun to do so I’ll go a bit further.

The problem is the following: we are given a list of numbers that represent a data structure. That data structure is basically a tree with tagged metadata. The goal is to parse the list of numbers to generate a memory representation of that tree and compute checksums on it. The structure is:

• A header, that has the number of children of a given node and the number of metadata entries.
• Zero or many children.
• At least one or many metadata entries.

The file format is made so that the data are nested. I’ll copy and explain an example:

2 3 0 3 10 11 12 1 1 0 1 99 2 1 1 2
A----------------------------------
    B----------- C-----------
                     D-----

Here, only the first line is present in the input file. The first 2 means that the first (A) node has two children (we don’t know anything about them yet) and the 3 means it has three metadata. Those are the header. Then, since it has two children, the next 0 is the start of the header of its first children (B), which has no child and three metadata (3). The next 10, 11 and 12 are then those metadata (since it doesn’t have any child). This node is then complete. If you go back up in the tree, you know that A still has another child. So the next number, 1, is the number of child of C and 1 its number of metadata. The next number 0 is the number of child of D and it has 1 metadata, which is 99. C, as seen above, has one metadata, so 2 is C’s metadata. Then, since A has three metadata, 1, 1 and 2 are its.

Pfiou. Seems hard to read for a human, right? However, if you’re used a bit to recursive data structure and more specifically recursive parsers, this kind of encoding is actually pretty neat!

Let’s go and implement the parser of that tree. First, the structure. We will not need the header in the output (it’s only used for parsing), so we will not encode that directly (it’s still available as the length of the list of children and length of the list of metadata entries):

data Node = Node {
    nodeChildren :: [Node],
    nodeMetadata :: NonEmpty Natural
  } deriving (Eq, Show)

Pretty simple, right? This is a self-recursing data structure that is pretty simple and basic to any functional programmer.

The NonEmpty a data type, in Haskell, is a list that cannot have zero element. That is enforced at compilation as it’s impossible to create such a list without explicitly giving at least one element. All the operations defined on NonEmpty a respect that rule (for instance, removing an element from it might not remove anything if it has only one element – otherwise you’d break its invariant and Haskell is not Javascript. Lol.

So, how do we parse that? I’ve already spoiled you the solution: we need to implement a recursive parser. I know that because I’ve been using parsec for like 7 years now, so I’m pretty used to that kind of parsing and as you use it, you will quickly recognize when you can use such an idiom.

However, instead of using parsec directly, I will implement it myself with some very basic types every Haskellers know – if you don’t: go learn them! I’ll be using the State type only, which is basically just a recursive function used in a monadic fancy way:

-- A possible representation of the State monad is just a function that takes a value 's' and
-- returns a new, altered 's' (we call that a state, but as you can see, it’s completely pure code,
-- no mutation happens at all) and an output value 'a'.
data State s a = State { runState :: s -> (s, a) }

The real State type is defined in the mtl Haskell library.

So here, you have the impression or illusion of s being a state, but what it truly is is just a value that is passed around to a recursive function – and plot twist: recursion is the way to implement locally-defined states, but I will not explain that (read my netwire tutorial and the Auto type, if you are interested).

The functor / monadic part:

instance Functor (State s) where
  fmap f = State . fmap (fmap f) . runState

instance Applicative (State s) where
  pure x = State (, x)
  p <*> q = State $ \s ->
    let (s', f) = runState p s
        (s'', a) = runState q s'
    in (s'', f a)

instance Monad (State s) where
  return = pure
  q >>= f = State $ \s -> let (s', a) = runState q s in runState (f a) s'

All of this can be generated automatically by GHC with deriving data annotation.

And some combinators we’ll need:

-- Get the current value of the “state”.
get :: State s s
get = State $ \s -> (s, s)

-- Get the current value of the “state” with a function pre-applied to it.
gets :: (s -> a) -> State s a
gets = flip fmap get

-- Change the value of the “state” by applying a function to the state.
modify :: (s -> s) -> State s ()
modify f = State $ \s -> (f s, ())

-- Just a convenient method to just get the output value and discard the final state. You need the
-- initial value to use as state.
evalState :: State s a -> s -> a
evalState st = snd . runState st

So basically, since this is a very basic and simple code (I think all Haskellers should write that in their first month using Haskell, it’s a good exercise), I just included the mtl library and used its State type to write my recursive parser.

This is my parser:

newtype Parser a = Parser { runParser :: State [Natural] a } deriving (Applicative, Functor, Monad)

So basically, a Parser a generates value of type a and maintains a list of Natural around. Those Natural are the numbers from the input we are going to parse. Let’s write the actual parser now.

-- Turns the (string-encoded) list of numbers and generates the root node, that contains all of
-- the children.
parse :: String -> Node
parse = evalState (runParser parseNode) . map read . words

-- Read a single number from the input and consume it from the state.
readInput :: Parser Natural
readInput = Parser $ gets head <* modify tail

parseNode :: Parser Node
parseNode = do
  -- We read the two first numbers (header)
  childrenNb <- readInput
  metadataNb <- readInput

  -- Recursive parser! The NE.fromList is an unsafe function that is used for convenience for this
  -- puzzle part.
  children <- replicateM (fromIntegral childrenNb) parseNode
  metadata <- fmap NE.fromList (replicateM (fromIntegral metadataNb) readInput)

  pure $ Node children metadata

As you can see, the parser code is extremely simple with a recursive combinator parser! And we’re actually done for the first part. The checksum is simple and is:

checksum :: Node -> Natural
checksum node = metadataChecksum (nodeMetadata node) + sum (map checksum $ nodeChildren node)

metadataChecksum :: NonEmpty Natural -> Natural
metadataChecksum = sum . NE.toList

Part 2

The second part is not interesting as it just requires a new method to compute the “value” of a given node:

nodeValue :: Node -> Natural
nodeValue (Node [] metadata) = metadataChecksum metadata
nodeValue (Node children metadata) = sum [nodeValue n | Just n <- map index (NE.toList metadata)]
  where
    index i =
      let i' = fromIntegral i - 1
      in if i' < 0 || i' >= length children then Nothing else Just (children !! i')

Haskell solution

Day 9: Marble Mania

Text

Part 1 & 2

This puzzle was the first one when I decided to go full Rust! All the remaining puzzles were solved in Rust – if you were reading only for Haskell, sorry for your loss. :(

This puzzle is not really interesting as it’s just a fancy algorithm that adds element to a collection and sometimes removes from it. There was a trick, though: the second part requires to run our algorithm on an input that was a hundred times larger.

The typical trap is that when you add value in the middle of a collection, the complexity in terms of memory and CPU can largely vary. Everything depends on what you do. For very rare additions / deletions, it’s possible that you can accept O(n) complexities. However, if you often insert stuff, you might want something else. In the same spirit, some data structure can efficiently add in O(1) at the beginning or end of the collection or might require a complete copy.

Even though the puzzle is not interesting in itself, it reminds us how crucial and critical it is that a programmer must know what structure to use depending on the inputs and operations that will be performed on the data. In our case, we are going to add and remove a lot at arbitrary places in the collection. Vectors are really bad candidates at that kind of operations, because they will require a complete scan of the right part of the collection, which is O(n), every time you add or delete something (to shift right / left, respectively). This is bad. Vectors are also bad when you want to add at its beginning (it requires the same right shift as the random case).

Double-ended queue (VecDeque in Rust) are a solution to the problem to insert at the beginning. That insertion is O(1) amortized.

My solution to this was to use a zipper to stay focus on a given number in the collection but also “move around” in O(1). The idea is the following:

struct Zipper {
  left: VecDeque<isize>,
  middle: isize,
  right: VecDeque<isize>,
}

When you want to move to the left, you just take the middle number and push_front it to the right double-ended queue and you pop_back the left one and that value becomes the new middle. You do the opposite thing to go to the right.

To insert an element at the current location, you just push_front middle to the right and then middle is assigned the new value. To remove, you just pop_front right into middle.

Then, the all puzzle is just adding and removing according to a predicate. Since all the operations I mentioned above run in O(1) amortized (they might allocate if the buffer is too small), we will not suffer from the typical O(n²) complexity a Vec implementation has.

Rust solution

Day 10: The Stars Align

Text

Part 1

This is the kind of problem I suck the most at. Not because they’re hard. Because they’re easier than expected. As an engineer, I tend to overthink about the context, the input’s hidden properties, the possible errors, the heuristics, what could go wrong, etc. On a regular job basis, that is actually a good thing – it’s better to foresee things than to have to repair them. However, at a given extreme, that way of thinking will make you go nuts and will make you think of an easy and straightforward problem as a complex and convoluted one. I know that and the main thing my mind does when solving a problem is to think about how really hard a problem is. I just completely failed on this one, haha. :D

So, you are given a short list (~360) of 2D points. You know nothing about how they’re spread nor the limits they lie in. You only have ~360 points on a 2D plane. Those points, however, come with two attributes:

• Their positions, as a pair of relative numbers ([-∞; +∞]).
• Their (constant) velocities, as a pair of relative numbers as well ([-∞; +∞]).

So basically, each point starts at a given position and goes into a straight line forever. The unit of the velocity is not known and is not really needed – even though it might be unit/s. Nevertheless, the text gives the hinting that, at a given (unknown) time, the points form a message that can be visually witness. The goal is to give the message.

In the first 15 minutes, I went through several thoughts. “Whoa, they want us to write an OCR?! Really?!”. Nah, you dumbass. Since we all have a unique input (and hence, a unique expected output), we don’t have to write an algorithm that can recognize any text. We just have to get to visualize our input.

However, when does the text appear? At t = 0, we have a large cloud of spread points. We don’t know when the text will form. Also, the challenge explicitly states that the text forms only once: the points will never gather into text afterwards. We must not miss it then.

My idea was that to find hidden properties of the overall text first. By being able to extract a useful information telling me whether or not I’m far or close from having a visualizable text, I was able to run a loop-like simulation, moving each points by its respectiv velocities, until that hidden information reaches a local minimum. As an engineer, I was annoyed by that, because I had no idea whether the first local minimum was the right one – the puzzle’s text doesn’t state anything about that and I had not found any information to help with that in the input. I could also use the wrong criteria (maybe we’re looking for a local maximum?). I got stuck with those ideas for long minutes.

Finally, I decided to implement a specific criteria:

• At each simulation step, we compute the AABB that encloses all the input points that have moved.
• If that AABB’s area is less then the previous one, we store the area, the width and height of the AABB and the current time of the simulation. We also print those values on the standard output.
• If not, we continue.

When I ran that loop, I got the first local minimum in 10011 seconds. Clearly, if you tried to actually run that simulation with the real time, you’d be waiting for a long time – 10011 seconds is 2 hours, 46 minutes and 51 seconds.

The size of the AABB at t = 10011 was also pretty small (around 60×60). I then decided to display the message directly in the console. In order to do that, I had to transform my 2D points (expressed in the natural ℝ² basis we use in world space coordinates) into a space that I could easily use to display (basically, [0; w] and [0; h]). That transformation is done with the following code:

// The rendered “map”
let mut lol = vec!['.'; w as usize * h as usize];

for p in points {
  let x = (p.position.0 - aabb.lower.0) * (w - 1) / w;
  let y = (p.position.1 - aabb.lower.1) * (h - 1) / h;
  let o = x + y * w;

  lol[o as usize] = '#';
}

Then, we just need to iterate on all the points and render them to the terminal to finish the challenge:

for row in 0 .. h {
  for col in 0 .. w {
    print!("{}", lol[(col + row * w) as usize]);
  }

  println!("");
}

Part 2

Part 2 was almost a joke: we were asked to give the time at which the text appeared. As this was a hidden property to find in the first place, completing part 2 took a few seconds: 10011.

Rust solution

Day 11: Chronal Charge

Text

Part 1

A pretty common algorithm to implement: sliding window. Basically, you are given a matrix of numbers and you have to compute several sums using a sliding kernel which size is 3×3. The size of the matrix is 300×300 and you just want to compute the biggest 3×3 square (and give its index in the matrix as row / column).

This was my solution:

let mut largest = (0, i8::min_value()); // (index, power)

// 298 is 300 - 2: we want to stop there so that the 3×3 square won’t overflow
for row in 0 .. 298 {
  for col in 0 .. 298 {
    let mut power = 0;

    // sum the square
    for i in 0 .. 3 {
      for k in 0 .. 3 {
        power += grid[index(col + i, row + k)];
      }
    }

    let i = index(col, row);

    // if its power is any larger, store it along with its index
    if (power == largest.1 && i < largest.0) || power > largest.1 {
      largest = (i, power);
    }
  }
}

println!("Largest fuel cell: ({}, {})", 1 + largest.0 % 300, 1 + largest.0 / 300);

That’s pretty much it. Second part is more interesting.

Part 2

For this part, the problem changes a bit: we still want to sum squares, but we want to get the find the square that has the largest total power of any size comprised between 1×1 and 300×300 – we want its index and its size.

That problem can be solved in several ways, with different complexities. It’s easy to see that you can quickly go with a bad complexity if you decide to refactor the previous algorithm to take a dimension (that will be squared) and call it 300 times. Maybe that would be enough.

However, I wanted to implement something smarter on this one. It’s easy to see that a lot of spanning squares will overlap. For instance:

+-+-+-+-+-+
|0|1|2|3|4|
+-+-+-+-+-+
|6|7|8|9|A|
+-+-+-+-+-+
|B|C|D|E|F|
+-+-+-+-+-+

If you consider the first, top-leftmost 2×2 square:

+-+-+
|0|1|
+-+-+
|6|7|
+-+-+

And the top-left-mostmost 3×3 square:

+-+-+-+
|0|1|2|
+-+-+-+
|6|7|8|
+-+-+-+
|B|C|D|
+-+-+-+

You can see that a the smaller one is included in the bigger one. What it means is that each spanning square is a partial sum to spanning square of a higher dimension. My algorithm benefits from that in order to reduce the number of elements to sum at each given dimension.

Also, another thing I did that suprised people on IRC: I reversed the way the algorithm works in terms of traversal. Instead of traversing dimensions and then traversing the grid (for all dimensions then for all squares), I traverse the grid and then I traverse the dimensions (for all square in the grid, for all the dimensions). This gives me a more natural way to write the partial sums in my code.

Finally, I also work out some formalæ to know “what’s the biggest dimension we can go up to given the current grid cell.” Yeah, think twice: when you want to go through all dimensions from the top-leftmost cell, you will be able to sum squares from 1×1 up to 300×300. But which dimension can you go to when the starting (1×1) cell is in the middle of the grid? This is actually pretty easy. The formalæ can be found very quickly by thinking in terms of size of the grid (300×300) and the index of a grid cell. The biggest dimension is just the minimum of the maximal allowed row iterations and the maximal allowed column iterations. You can picture that mentally by “which edge I am the closest to?”. For rows, it’s simply 300 - current_row and for columns, 300 - current_column. The minimum value gives you the maximal spanning dimension you can go up to.

Finally, a word on how the partial sums are created: when you start computing the sum of the N dimension, you already have the partial sum of dimension N-1 (the algorithm starts with the first dimension set to a given value). Then, instead of summing N² element, since you already have the sum of (N-1)², you just need to sum 2 × (N - 1) + 1 values. If you’re not convinced, at dimension 278, 278² = 77284 sums while my algorithm is 2 × (278 - 1) + 1 = 555 sums. It’s around 139 times less.

In my code, I do that by adding – relative to the previous spanning square – the right column (which size is N - 1), the bottom line (N - 1 as well) and the single element in the diagonal. Hence 2 × (N - 1) + 1. And that completes a new partial sum, that will be used for higher dimensions!

Here’s just a very quick schema to show you how to compute the sum at dimension 5 by using the sum of the spanning square of dimension 4 – · is already computed and R are the right column, B the bottom line and D the element in the diagonal:

+-+-+-+-+-+
|·|·|·|·|R|
+-+-+-+-+-+
|·|·|·|·|R|
+-+-+-+-+-+
|·|·|·|·|R|
+-+-+-+-+-+
|·|·|·|·|R|
+-+-+-+-+-+
|B|B|B|B|D|
+-+-+-+-+-+

So, here’s the code:

let mut largest2 = (0, i64::min_value(), 0); // (index, power, dimension)

// for all rows…
for row in 0 .. 300 {
  let max_iter_row = 300 - row; // 300 -> 1

  // for all columns…
  for col in 0 .. 300 {
    let max_iter_col = 300 - col; // 300 -> 1
    let max_dim_squared = max_iter_row.min(max_iter_col); // 300x300 -> 1x1

    // power used for nested dimensions
    let mut nested_power = grid[index(col, row)] as i64;

    // note: we don’t have to compute the first dimension because it’s set right away to the given
    // nested power

    // for all dimensions up to the max
    for d in 1 .. max_dim_squared {
      let mut power = nested_power;

      // compute the 2 × (N - 1) elements
      for k in 0 .. d {
        power += grid[index(col + d, row + k)] as i64;
        power += grid[index(col + k, row + d)] as i64;
      }

      // add the diagonal
      power += grid[index(col + d, row + d)] as i64;

      let i = index(col, row);

      if (power == largest2.1 && i < largest2.0) || power > largest2.1 {
        largest2 = (index(col, row), power, d + 1);
      }

      nested_power = power;
    }
  }
}

println!("Largest fuel cell of all: ({}, {}, {}, of power {})", 1 + largest2.0 % 300, 1 + largest2.0 / 300, largest2.2, largest2.1);

Rust solution

Day 12: Subterranean Sustainability

Text

Part 1

This puzzle looked a bit like the double-ended queue one from day 9. The extra bit of information is that you now have to apply a pattern on several values to know how they should be mutated. Given a list of flower pots and some rules that give you how a pot should grow flowers (or not) according to the state of itself and its neighbors, the goal is to predict the sum of the pots (their index in the list) for all pots that contain flowers after 20 generations.

In the first place, I had to recognize that I needed a double-ended queue. As always, the puzzle’s text doesn’t explicitly tell you that the pots at leftmost and rightmost positions can “spawn” new pots by applying the rules on empty pots (infinite). I was confused at that for a while.

My encoding of rules is pretty simple and wasteful: since a rule gives you a pattern (which pots) and an output (should have flowers / shouldn’t), a single byte should be enough for that (the length of a rule is five: it gives you the state of the two left neighbors, the state of the current pot and the state of the two right neighbors). However, I encoded those with a simple array of five binary states (Rule::Empty and Rule::Pot).

In order to apply a pattern, we must retreive the current pot and two at its left position and two at its right position (if pots are missing because we’re at edges, we must spawn empty pots with negative / positive indices). Then we can just apply the pattern by looking it up in a hashmap: we get the next generation value.

Nothing really interesting code-wise to show here.

Part 2

Part 2 is funny. We’re told that instead of finding the sums after 20 generations, we need to find it after fifty billion (50000000000) generations. Obviously, trying to run the above algorithm for 50000000000 generations will take ages, so we need to find a better way.

My first inital idea was that if I took a look at the actual sum value at each generation, I could – perhaps – see some kind of patterns. At first I was looking for cycles and hence cycling sums. I then run my algorithm and had a look at the output data. I was suprised to find that, very quickly, the flowers grow linearily. What it means is that, after a given number of generations, you can guess how many flowers there will be at a given future generation by applying a linear formula (typically, a simple multiplication and addition).

In my case, I noticed that at generation 100, the sum was 6346. At 101, it was 6397. At 102, it was 6448. At 200, it was 16546. You can see the pattern – if you don’t, compute the difference between the sum at 101 and the sum at 100… and the difference of sum at 102 and 101.

Hence, I came up with the following linear formula:

// O(1) get the score at a given generation – works only for gen ≥ 100.
fn score_at(gen: u64) -> u64 {
  6346 + (gen - 100) * 51
}

The actual implementation uses 101 instead of 100 because we want to get the sum after a given number of generations, not at.

That kind of linear optimization was really fun to write yet a bit tricky to find. :)

Rust solution

Day 13: Mine Cart Madness

Text

Part 1

I think this was the puzzle I enjoyed the most – among the ones I did. The goal is to parse is rails map on which wagons go and make wagons move around by respecting some specific rules: we must find wagon collision is report their positions 2D position.

Parsing is actually pretty simple: the input data is the 2D map that contains the rail system along with the initial position of wagons. About the map, I decided to store only crossings, not the actual rails, because I didn’t need them! So in order to do so, I changed a bit the regular way I encode 2D maps in memory and decided to use a hashmap!

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Rail {
  Cross, // +
  RampRight, // /
  RampLeft // \
}

struct Map(HashMap<(u32, u32), Rail>);

The rest of the code is actually pretty simple: there are several functions, one for moving carts, one for changing directions at cross, one for detecting collision. A main loop is responsible in moving carts and checking if there’s any collision. If no collision is detected, we just loop back up. If a detection is detected, we break the loop and display the position of the crash. The collision algorith returns the IDs of the carts that collided into each other.

let collision = loop {
  // sort the cart by y component
  carts.sort_by(|a, b| a.pos.cmp(&b.pos));

  let collisions = move_carts(&map, &mut carts);
  if !collisions.is_empty() {
    break collisions[0];
  }
};

println!("First collision: {:?}", carts[collision.0].pos);

The sort_by is needed because of priority rules in the puzzle’s text.

Moving carts and detecting collision is pretty straightforward:

fn move_carts(
  map: &Map,
  carts: &mut Vec<Cart>,
) -> Vec<(usize, usize)> {
  let mut collisions: Vec<(usize, usize)> = Vec::new(); // no collision to begin with

  // move and check collision for all carts
  'outer: for i in 0 .. carts.len() {
    // check that this cart hasn’t been collided into yet
    for &collision in &collisions {
      if i == collision.0 || i == collision.1 {
        // already collided, don’t move that
        continue 'outer;
      }
    }

    // move the cart and check if it’s collided into another
    move_cart(map, &mut carts[i]);
    let collision = find_collision(&carts, i);

    if let Some(collider) = collision {
      collisions.push((collider, i));
    }
  }

  collisions
}

This code is not really optimized – we redo the same thing very often – but it’s way than enough to solve that puzzle’s part. Finding collision is very simple: we just try to find a cart with the same position.

The tricky part is for moving at cross. The rules state that if you arrive at a cross, you have to turn in a given direction and change the future direction you will take at the future cross, if any. This was encoded inside each cart, so that they have a “memory” of turns to take.

#[derive(Debug)]
struct Cart {
  pos: (u32, u32),
  dir: Direction,
  next_turn: Turn
}

A cart starts by going on its (relative!) Turn::Left, then at the next turn it will go Turn::Straight, then Turn::Right and finaly will loop back to Turn::Left. Note how different it is to Direction: a Turn is relative to the current movement of a cart while a Direction is absolute (at first, I wanted to have North, East etc. for Direction so that confusion is not possible).

Part 2

In that part, we want to find the last standing cart, assuming that crashing carts are immediately removed from the map. The code is actually very similar: instead of breaking the loop at the first collision, we break it when there’s only one cart left on the map – we don’t forget te remove the crashed carts!

loop {
  // sort the cart by y component
  carts.sort_by(|a, b| a.pos.cmp(&b.pos));

  for (ci, ck) in move_carts(&map, &mut carts) {
    carts = carts.into_iter().enumerate().filter(|&(i, _)| i != ci && i != ck).map(|(_, c)| c).collect();
  }

  if carts.len() == 1 {
    break;
  }
};

println!("Last standing cart: {:?} ", carts); // this contains only one cart

Rust solution

Day 14: Chocolate Charts

Text

Part 1

Very similar to the double-ended queue puzzle as well, this one doesn’t actually require any deletion, just indexing correctly into a growing buffer. Nothing really interesting to show about this problem, except maybe the way recipes are created.

To create new recipes, the two Elves combine their current recipes. This creates new recipes from the digits of the sum of the current recipes’ scores. With the current recipes’ scores of 3 and 7, their sum is 10, and so two new recipes would be created: the first with score 1 and the second with score 0. If the current recipes’ scores were 2 and 3, the sum, 5, would only create one recipe (with a score of 5) with its single digit.

In order to implement that, I recognized that I will always create at least one recipe: 0 + 0 = 0, and as soon as I create two recipes, the other one will always be 1, because the maximum value is 9 + 9 = 18 (1 and 8). Here’s my code that gets those two recipe numbers:

fn create_new_recipe(a: usize, b: usize) -> (Option<usize>, usize) {
  let s = a + b;
  let x = s / 10;
  let y = s % 10;

  (if x == 1 { Some(x) } else { None }, y)
}

Part 2

Part 2 is really not interesting as it’s just using ends_with to find a suffix. I’ll let you read the code if you’re interested.

Rust solution

Day 15: Beverage Bandits

Text

Part 1

Aaaaaaaaaand this is the last puzzle I attempted. I actually decided not to finish it because it was taking me time. I will tell you more about that in the conclusion.

The goal is to write a simulation of elves fighting goblins (or goblins fighting elves) and finding paths in a map that has holes / mountains in it. So most of the code to write is about Dijkstra or A*. The puzzle seemed interesting but it was way too much for my spare time to spend on. I advise you to have a look at the insanely long puzzle’s text – that will give you an idea of everything you need to implement in order to get the your solution working.

Conclusion

Ah, my first Advent of Code. It was both interesting, exciting, frustrating and time-consuming. I found several pros and drawbacks:

Pros, first:

• It’s all fun. Since I live in France, I couldn’t compete with people who get the puzzles unlocked in the morning around 10:00 AM while they were unlocked around 5:00 AM in France – I have a job, I have to, you know… SLEEP! So I just did it for fun.
• Writing algorithms to solve math and operational problems is always interesting and makes it a great training.
• Comparing solutions on IRC was also pretty fun!

And drawbacks:

• The fact west-europeans cannot compete (the timezone issue).
• The difficulty of the puzzles is not correctly balanced. Some puzzle are insanely simple to solve and some others take you hours (if not days if you don’t have a lot of spare time). Sometimes I felt frustrated at this, because I’ve been lacking sleep time for weeks and had to go to bed in order not to destroy my physical health. I’m curious to hear about other west-europeans: how did you manage your time, social life and work life with AoC?
• Some problems had a very long first part 2 and the second part was really stupid (read The Stars Align – Part 2). I would have preferred to have more consistency or more parts, for instance.

My general feeling is that it was fun, but I think that I won’t do it next year, because I had to put all my spare projects on hold for that. I didn’t learn anything new – all the algorithms had me write algorithms I already knew, except maybe the partial dimension squared algorithm I “invented”: someone told me that it’s very similar to a real and well-known algorithm! How funny is that! The algorithm is Summed-area table and my solution is, indeed, very similar to it. But the thing is: I came up with the idea, and this is priceless for training brains!

Now I’ll return to my graphics, Rust and over experiment projects of mine! I hope you liked that article, it was a bit long (it took me almost two weeks to write!) but I felt I needed to make it. To… well… scrap and forget about Advent of Code and all my spare time I didn’t use for my own projects. :)

Keep the vibes – especially you, @lqd.

I just added a new feature to warmy to make it more accessible and easy to use. It concerns JSON and serde.

Universal JSON support in warmy 0.11.1

If you’ve been using warmy a bit, you might be used to its traits and structures, like Load, Loaded, Load::reload, Res, etc. All those concepts are mandatory to implement loading, reloading and scarce resource sharing. Since version 0.7, warmy has got loading and reloading methods. That feature enables you to have several impl for the same type of resource by changing the method used to load. The default is () but you’re free to use any you want. The idea is that you can call the Store::get_by or Store::get_proxied_by methods to specify which method to use explicitly when loading and reloading a given resource.

warmy 0.11.1 uses that concept to provide a universal implementor for anything that implements the Deserialize trait from serde. Basically, once your type implements Deserialize, you can load and hot-reload values of this type by using the Json type from warmy.

Universal JSON implementors are available only if the "json" feature is enabled in warmy. It’s the case by default. Feel free to use default-features = false if you don’t want it.

Here’s a short example of what it looks like to load and hot-reload a Dog using the universal JSON feature:

use serde::Deserialize;
use warmy::{Res, SimpleKey, Store, StoreOpt};
use warmy::json::Json;
use std::thread::sleep;
use std::time::Duration;

#[derive(Debug, Deserialize)]
#[serde(rename_all = "snake_case")]
struct Dog {
  name: String,
  gender: Gender
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
#[serde(rename_all = "snake_case")]
enum Gender {
  Female,
  Male
}

fn main() {
  let mut store: Store<(), SimpleKey> = Store::new(StoreOpt::default()).unwrap();
  let ctx = &mut ();

  let resource: Result<Res<Dog>, _> = store.get_by(&SimpleKey::from_path("/dog.json"), ctx, Json);

  match resource {
    Ok(dog) => {
      loop {
        store.sync(ctx);

        println!("Dog is {} and is a {:?}", dog.borrow().name, dog.borrow().gender);
        sleep(Duration::from_millis(1000));
      }
    }

    Err(e) => eprintln!("{}", e)
  }
}

This feature should help people adopt the crate and use it without worrying too much about the actual implementation of Load.

If you’re interested in adding other methods, like YAML, XML or whatever, feel free to open a PR on GitHub! I’ll be very happy to accept it. More documentation about the feature can be found in the README or the online documentation.

Keep the vibes.

Oh hello there! It’s been a while since I wrote on here. My last article was posted on February 25th and then I decided it was time to blog more about what I do. Especially, I think I will try to blog more often, even if it’s about trivial things, as long as I share my thoughts.

So today, I’m going to talk about the splines crate. And more specifically, the splines-1.0.0-rc.1 release candidate I uploaded today on crates.io.

Foreword: you said splines?

Maybe you’re wondering what a spline is, in the first place. A spline is a mathematic curve that is defined by several polynomials. You can picture them mentally by several small and simple curves combined to each others, giving the curve an interesting shape and properties. Now why we want splines is easy to understand: imagine a curve, something smooth and a bit complex (maybe even with loops). Now, imagine you want to make an object move along that curve. How do you represent that curve and how to you “make something advance along it?”

Splines are defined by several “control points”, also known “keys”, “knots” or whatever makes sense to you. Those are just points of interest that will have a direct impact on how the curve will bend and behave. Most of control points have the interesting property that the curve will pass through them, allowing you to define points you want your object to pass by, for instance. Not all control points have that property, though.

Now all the magic happens with those control points: when you want to sample a value at a given control point, you just get back the value carried by this control point… but when you want to sample in between two control points, for instance, you get back an interpolated value. That interpolation is the key to why we want splines. Several interpolation mechanisms exist and I’m sure you know at least two:

• Constant interpolation: it means that given two control points, sampling at the first control point or any part between the control points will give you the carried value of the first control point. You will get the carried value of the second control point if you sample at its sampling value. That might be like a useless feature but it is very handy when designing and implementing “stop-by” movement with camera.
• Linear interpolation: this one you might know it, especially if you attended math courses at high-school. Linear interpolation is often referred to as “drawing a straight line”. And typically, “everything linear” can often graphed with a straight line! Thank about linear complexity (O(n)) and what it looks like on a graph. Linear interpolation that gives you a strict blending of arguments depending at which distance you sample from them. If sample at t = 0, you get 100% of the first value and 0% of the second value. If you sample at t = 0,5, you get an equal amount of both value (so you get the mean between both value). At t = 1, you get 0% of the first value and 100% of the second value. Simple but really useful.
• Cosine interpolation: this one is known by people who are used to animation, graphics, motion design, etc. Cosine interpolation gives you a smoother interpolation than the linear one and provides a first derivative that is more interesting (i.e. it translates to acceleration).
• Others: splines provide you with some other interpolation modes and some (that I really want!) are missing. For instance, cubic Bézier interpolation is something I want and that I already have coded in the Haskell version of the splines crate. It should be easy to add but so far, no one has asked for them and I don’t need them, so… ;)

Keep in mind that a spline is a just an abstractio mathematical object and that you can use it for lots of concepts and situations. For instance, in demoscene productions of mine, I use splines for camera movement, animation transitions, color-blending and more!

The splines crate

The splines crate has been around for some time now and I received some feedback from people on the GitHub page asking for more features. Basically, the crate can now:

• Support failible sampling more sanely (instead of panicking on some very trick situations, you get a None).
• Support for polymorphic sampling types (you have f32 but also f64 or whatever).

I think something interesting to dissect in this blog article is the last feature about polymorphic sampling types and what I had to do in order to make it happen. Also, this is highly correlated to a design choice I have made months ago: supporting foreign crates to interpolate specific types is done inside the splines crate, not in other crates. I will discuss why just bellow.

Polymorphic sampling

Basically, in splines, prior to 1.0.0, a spline was polymorphic type mapping a key of type f32 to a control point of type Key<V>, V being the carried value. You then manipulate a Spline<V>. The problem with that is whenever someone wants to use a different time, like, f64 or something of their own.

My first solution was to turn the spline type to Spline<T, V>. That would allow people to use both f32 and f64 as sampling type. The problem kicks in with the code handling those sampling values. For instance, for the Interpolation::Cosine interpolation mode, I need to take the cosine of a value which type is either f32 or f64. How can we do that in a generic and polymorphic maneer?

num-traits to the rescue!

Yeah, so was my first thoughts. I then re-wrote most of the interpolating code using num-traits… and then decided to tackle all the feature gates. Because, I haven’t told you yet, but splines has several feature gates allowing you to use, e.g., implement the Interpolate trait for some famous crates’ types (nalgebra, cgmath), enable serde serialization, etc. One feature gate that is important to me as a demoscener is the "std" feature gate, that, if not defined, makes the splines crate compile with the no_std feature.

And here comes the first problems. The num-traits has a trait that isn’t compatible with no_std, the Float trait. I then sat in front of my computer and thought. I came to the realization that whatever library I would use for that trait, I would always get my hands tied by the contracts of the public interface of that crate, for a feature that is almost central to the whole splines crate. It quickly became obvious that I couln’t use num-traits.

Yes, I know about the FloatCore trait. However, I was stuck with FloatConst right after that and I just wanted to clean the interface.

The monomorphic version of splines is easy to implement for no_std, but now I’m stuck because of some simple traits? Naaah.

So I decided to write my own traits. Enter: Additive, a simple trait with no content but Add and Sub as supertraits (and some non-important ones for comprehension here), One, a trait that provides the neutral element of the multiplication for a given type (i.e. the multiplication monoid) and the Linear<T> trait, providing linear combinations, mandatory for all kind of interpolations mentioned earlier.

Those traits have universal implementors so that you don’t have to implement them. And enabling a feature gate for, e.g., cgmath will also implement those traits accordingly in an enough polymorphic way that you shouldn’t have to ever worry about them.

Just a little remark of mine: implementing the support for cgmath was pretty simple and straight-forward. As feared (because I used this crate), nalgebra was way harder to get right — and I even decided not to implement the Point<..> type because I’ve been struggling all the afternoon with error types that reminded me old and dark times with C++ Boost library. I’ve already discussed that with people from the nalgebra world and none seemed to agree with me that this crate is a little bit too overengineered. For instance, adding the support for nalgebra in splines also adds several mandatory dependencies — i.e. num-traits and alga. It’s not that bad, but if you want to play with simple vector spaces, I really do not recommend nalgebra as it’s a really convoluted library with lots of type aliases and types with infinite counts of type variables. Maybe it’s just a confirmation bias of mine, because I’ve always used (and written, back then in C++) linear libraries that were both simple and fast. nalgebra makes me think of this and this is driving me crazy. I’m not saying it’s bad. I’m saying it’s not for me and that I wouldn’t recommend it for people wanting to do simple things — and yes, video game still falls in that simple things bag.

Let’s talk about feature gates

So, the design of feature gating in splines. I know it might feel a bit weird to have gates like "impl-nalgebra" or "impl-cgmath" but to me it makes lots of sense. For a simple reason: a crate exposes several types and functions via its public API. Everything that is not public is not for a very good reason. Mostly, invariants. An invariant is something that must remain true before a function / morphism / whatever is called and after. What happens in between can actually break that invariant. The idea is that “If a function breaks internally an invariant, it must restore it before returning”, so that the API remains safe to use.

Invariants are central in my way of thinking. Everytime I write some code, everytime I design an interaction between several piece of algorithms, crates or even cross-language and cross-systems, I always asks myself “Am I breaking an invariant here? Is it possible to fuck up a state or a hidden property somewhere?”

In Rust, invariants are not a first-class citizen of the language (have a look at how the D language handles invariant: it’s interesting!). However, they still exist. Imagine this piece of code:

pub struct Even(pub u64);

impl Even {
  pub fn new(nth: u64) -> Self {
    Even(nth * 2)
  }
}

impl Add<u64, Output = Even> for Even {
  fn add(self, rhs: u64) -> Output {
    Even(self.0 + rhs * 2)
  }
}

Imagine this is wrapped in a crate num-even. Adding a u64 to an Even gives you the nth next even number. All of this is cool. But there is an invariant. The carried u64 by Even must… remain even. If at some time a user handle a Even with an odd u64 inside of it, something has gone wrong terribly. And with this current implementation, it’s very easy to break such an invariant. Consider:

use num_even::Even;

fn main() {
  let mut a = Even::new(1); // the 1st even number
  a.0 += 1; // oooooooh, fuuuuuuu-
}

I had long heated debates with people on IRC about why this kind of library should be patched. The main argument of people who would think it shouldn’t be patched is “Yeah but we want users to have access to the underlying objects in any way they want.” I think invariants matter most. The patch version is actually a negative diff:

pub struct Even(u64);

Done. Here, the invariant cannot be broken anymore because people cannot create or modify Even by hand. Constraining is powerful. You should try it. :)

splines holds keys in a Spline<..> that must remain sorted. Hence, you don’t have a direct access to the keys nor you can mutate them. Mutating keys would imply resorting the keys in a smart way, which is something I haven’t needed yet.

So, that’s all for me for today. If you have any question about splines, please feel free to open an issue on GitHub. Also, if you’re interested in trying it, please have a look at the splines-1.0.0-rc.1 release candidate. It contains everything you need to get started!

The documentation is not up to date and some is missing, but it should be enough to start.

As always, keep the vibes!

Well, I’ve changed my mind. Some people pointed out that the good thing to do for most GPU is to align on 32-bit. That is, 4 bytes. The alignment should be 4 bytes, then, not 1.

There might be an issue with that. If you store a structure with attributes which sizes are not a multiple of 4 bytes, it’s likely you need to add padding.

However, I just reviewed my code, and found this:

instance (GPU a,KnownNat n,Storable a) => Vertex (V n a) where
instance (Vertex a,Vertex b) => Vertex (a :. b) where

Those are the single instances for Vertex. That means you can only use V and (:.) to build up vertices. Look at the V instance. You’ll find a GPU typeclass constraint. Let’s look at its definition and instances:

class GPU a where
  glType :: Proxy a -> GLenum

instance GPU Float where
  glType _ = GL_FLOAT

instance GPU Int32 where
  glType _ = GL_INT

instance GPU Word32 where
  glType _ = GL_UNSIGNED_INT

Woah. How did I forget that?! Let me translate those information to you. That means we can only have 32-bit vertex component! So the memory inside vertex buffers will always be aligned on 4 bytes! No need to worry about padding then!

The first implication is the fact you won’t be able to use Word16, for instance. You’ll need to stick to the three types that have a GPU instance.

Note: that doesn’t prevent us from adding Double later on, because a Double is a 64-bit type, which is a multiple of 4 bytes!

That’s all I have for today. I’m working on something very exciting linked to render batching. I’ll talk about that when it’s cooked. ;)

Keep the vibe; keep building awesome things, and as always, thank you for reading me!

luminance-0.1 was released yesterday night, along with luminance-samples-0.1! I’ll need to enhance the documentation and add directions so that people don’t feel too overwhelmed.

I’m also going to write a wiki to help people get their mind wrapped around luminance.

If you think something is missing; if you think something could be enhanced; or if you’ve found a bug, please, feel free to fill in an issue on the issues tracker.

Next big steps

I need to test the framework. I need a lot of tests. I’ll write a demoscene production with it so that I can give a good feedback to the community and prove that luminance can be used and works.

In the waiting, keep the vibe!

It’s been a while I haven’t released anything on my blog. I just wrote a few changes for the latest version of luminance, luminance-0.8.2 and I decided to write about it because I think those changes are interesting on a Haskell level.

The problem

If you haven’t read the changelog yet, I changed the createProgram function and the way it handles uniform interfaces. In luminance < 0.8, you were provided with as many functions as there are uniform kinds. Up to now, luminance supports two uniform kinds:

• simple uniforms;
  • uniform block (UBO).

So you had two rank-2 functions like forall a. (Uniform a) => Either String Natural -> UniformInterface m (U a) and forall a. (UniformBlock a) => String -> UniformInterface m (U (Region rw (UB a))) to map whichever uniforms you wanted to.

The issue with that is that it requires to break the interface of createProgram each time we want to add a new kind of uniform, and it’s also a pretty hard to read function signature!

So… how does luminance-0.8 solve that?

(Generalized) Algebraic data types, rank-2 and existential quantification

What is the only way we have to select uniforms? Names. Names can either be a String or a Natural for explicit semantics. We could encode such a name using an algebraic data type:

data UniformName
  = UniformName String
	| UniformSemantic Natural
	  deriving (Eq,Show)

That’s a good start. Though, we still have the problem of choosing the kind of uniform because we still have several functions – one per kind. We could encode the kind of the uniform directly into the name. After all, when we ask for a uniform mapping through a name, we require to know the kind. So that kind of makes sense. Let’s change our UniformName type:

data UniformName :: * -> * where
  UniformName :: String -> UniformName a
	UniformSemantic :: Natural -> UniformName a
	UniformBlockName :: String -> UniformName (Region rw (UB a))

That’s neat, but with that definition, we won’t go anywhere, because we’re too polymorphic. Indeed, UniformName "foo" :: UniformName a can have any a. We need to put constraints on a. And that’s where GADTs come in so handy! We can hide the constraints in the constructors and bring them into scope when pattern matching. That’s a very neat feature of GADTs. So now, let’s add some constraints to our constructors:

data UniformName :: * -> * where
  UniformName :: (Uniform a) => String -> UniformName a
	UniformSemantic :: (Uniform a) => Natural -> UniformName a
	UniformBlockName :: (UniformBlock a) => String -> UniformName (Region rw (UB a))

Yes! Now, we can write a function that takes a UniformName a, pattern matches it and call the appropriate function regarding the infered shape of a!

However, how do we forward the error? In older version of luminance, we were using ProgramError and more especially two of its constructors: InactiveUniform and InactiveUniformBlock. We need to shrink that to a single InactiveUniform constructor and find a way to store our UniformName… But we can’t yet, because of the a parameter! So the idea is to hide it through existential quantification!

data SomeUniformName = forall a. SomeUniformName (UniformName a)

instance Eq SomeUniformName where
  -- …

instance Show SomeUniformName where
  -- …

And now we can store SomeUniformName in InactiveUniform. We won’t need to recover the type, we just need the constructor and the carried name. By pattern matching, we can recover both those information!

Conclusion

Feel free to have a look at the new createProgram function. As you will see, the type signature is easier to read and to work with! :)

Have fun, and keep the vibe!

Abstracting what?

Shaders are very common units in the world of graphics. Even though we’re used to using them for shading¹ purposes, they’re not limited to that. Vulgarisation has ripped off the meaning up and down so much that nowadays, a shader might have nothing related to shading. If you’re already doing some graphics, you may know OpenGL and its compute shaders. They have nothing to do with shading.

You might also already know shader toy. That’s a great place to host cool and fancy OpenGL shaders². You write your shaders in GLSL³ then a GLSL compiler is invoked, and your shader is running on the GPU.

The problem with source based shaders

So you write your shader as a source code in a host language, for instance in C/C++, Java, Haskell, whatever, and you end up with a shader running on GPU.

There’re two nasty issues with that way of doing though:

• the shader is compiled at runtime, so if it contains error, you’ll know that after your application starts ;
• you have to learn a new language for each target shader compilers.

They’re both serious issues I’m going to explain further.

Issue n°1: compiled at runtime

This is problematic for a good reason: a lot of shaders are application dependent. Shadertoy is a nice exception, just like modeling tools or material editors, but seriously, in most applications, end users are not asked the shaders to run with. In a game for instance, you write all the shaders while writing the game, and then release the whole package.

Yeah… What’s about additional content? Per-map shaders, or that kind of stuff?

Those shaders are like resources. That doesn’t imply using them as is though. We could use dynamic relocatable objects (.so or .dll) for instance.

What compile-time compilation gives you?

It gives you something hyper cool: host language features. If you have a strongly-typed language, you’ll benefit from that. And that’s a huge benefit you can’t get away from. If you’re writing an incorrectly typed shader, your application / library won’t compile, so that the application won’t react in weird way at run-time. That’s pretty badass.

Issue n°2: languages, languages…

This issue is not as important as the first one, but still. If you’re working on a project and you target several platforms (among ones using OpenGL, OpenGL ES, DirectX and a soft renderer), you’ll have to learn several shading languages as well (GLSL, HLSL⁴).

In order to solve that, there’re two ways to go:

• a DSL⁵ ;
• an EDSL⁶.

A DSL is appealing. You have a standalone language for writing shaders, and backends for a compiler/language. However, that sounds a bit overwhelming for such an aim.

An EDSL is pretty cool as well. Take a host language (we’ll be using Haskell) and provide structure and construction idioms borrowed from such a language to create a small embedded one. That is the solution I’m going to introduce.

Ash

Ash stands for Abstract Shader. It’s a Haskell package I’ve been working on for a few weeks now. The main idea is:

• to provide a typesafe shading language compiled at compile-time;
• to provide backends;
• to provide a nice and friendly haskellish interface.

I guessed it’d be a good idea to share my thoughts about the whole concept, since I reckon several people will be interested in such a topic. However, keep in mind that Ash is still a big work in progress. I’m gonna use several blog entries to write down my thoughts, share it with you, possibly enhance Ash, and finally release a decent and powerful library.

If you’re curious, you can find Ash here.

Basics

Ash is a library that provides useful tools to build up shaders in Haskell. In Ash, a shader is commonly function. For instance, a vertex shader is a function that folds vertex components down to other ones – possibly maps, but it could add/remove components as well – and yields extra values for the next stages to work with.

You write a shader with the Ash EDSL then you pass it along to a backend compiler.

Here are two examples. In order for you to understand how Ash works, I’ll first write the GLSL (330 core) shader, then the Ash one.

First example: a simple vertex shader

Let’s write a vertex shader that takes a position and a color, and projects the vertex using a perspective matrix, a view matrix and the object matrix of the object currently being rendered and passes the color to the next stage:

#version 330 core

in vec3 pos;
in vec4 col;

out vec4 vcol;

uniform mat4 projViewModel;

void main() {
  vcol = col; 
  gl_Position = projViewModel * vec4(pos, 1.);
}

And now, the Ash one:

vertexShader :: Ash (M44 Float -> V3 Float :. V4 Float -> V4 Float :. V4 Float)
vertexShader = lam $ \proj -> lam $ \v ->
  let pos :. col = v
  in proj #* v3v4 pos 1 :. col

Ash is the type used to lift the shading expression up to Haskell. You use it to use the EDSL. It actually represents some kind of HOAST⁷.

Then, you can find M44, V3, V4 and (:.).

M44 is the type of 4x4 matrices. Since projection matrix, view matrix and model matrix are all 4x4 floating matrix, M44 Float makes sense.

V3 and V4 represents 3D and 4D vectors, respectively. V3 Int is three ints packed in a vector as well as V4 Float is four floats packed in a vector. You’ll also meet V2, which is… the 2D version.

(:.) is a type operator used to build tuples. You can see (:.) as a generalized (,) – the default Haskell pair type – but (:.) is more power full since it can flatten expressions:

a :. (b :. c) = a :. b :. c

The (:.) has a lot of uses in Ash. In our cases, a chain of (:.) represents a vertex’ components.

So our vertexShader value is just a function that takes a matrix and a vertex (two components) and outputs two values: the new position of the shader, and the color. Let’s see the body of the function.

lam $ \proj -> lam $ \v ->

This is a pretty weird expression, but I haven’t found – yet? – a better way to go. lam is a combinator used to introduce lambdas in the EDSL. This expression then introduces a lambda that takes two values: proj and v. You can read that as:

\proj v ->

Next:

let pos :. col = v

This is the tricky part. That let expression extracts the components out of the vertex and binds them to pos and col for later use.

in proj #* v3v4 pos 1 :. col

(#*) is a cool operator used to multiply a matrix by a vector, yielding a new vector.

(v3v4) is a shortcut used to to build a V4 using a V3 by providing the missing value – here, 1. You’ll find similar functions, like v2v3 and v2v4, to respectively build a V3 from a V2 by providing the missing value and build a V4 from a V2 by providing the two missing values.

We finally wrap the result in a tuple (:.), and we’re done.

Features

Ash embeds regular linear expressions (vectors, matrix), textures manipulation, tuples creation, let-bindings, lambda functions (they represent shader stages up to now), and a lot of other features.

Each feature is supposed to have an implementation in a given backend. For instance, in the GLSL backend, a lambda function is often turned into the well done main function. Its parameters are expanded to as in values, and control parameters are uniform variables.

Each backend is supposed to export a compile function – the name may varies though. However, each backend is free to compiles to whatever smart they think is. For instance, compiling an Ash shader to GLuint (shader stage) is not very smart since it would use IO and handles error a specific way we don’t want it to do. So the GLSL compiler is a function like glslCompile :: Ash … -> Either CompilationError String, and the String can be used as a regular GLSL source code string you’ll pass to whatever implementation of shader you’ve written.

What’s next?

I need to finish the implentation of the EDSL, and write the whole GLSL 330 compiler. If it’s a success, I’ll accept pull-requests for other famous compilers (other GLSL version compilers, HLSL, and so on and so forth).

Once that done, I’ll write a few other blog entries with example as a proof-of-concept :)

Soooooooooooo. Because glsl is written with nom in its third iteration and because nom is now at version 4, I decided it was time to update the parser code of glsl. I heard about the comparison between pest and nom and decided to write an implementation with pest.

This is the first article of a series about how writing a pest looks like is fun compared to writing the nom parser. I’ll post several articles as I advance and see interesting matter to discuss and share.

• Second article here

Oh my; I love PEG!

First thing first: pest consumes a file at compile-time that contains a PEG grammar defining the format of input you want to parse. PEG – which stands for Parsing Expression Grammar – is a formal language that enables you to describe your own language with rules. Those rules are written with some basic blocks that belong to Language Theory – if you’ve ever heard of Stephen Kleene and its famous Kleene star for instance, you will feel familiar with PEG.

What I love about PEG is that with a very limited set of constructs, you can describe a lot of determinist languages. In the case of GLSL450 – which is the language that the glsl crate can parse – it’s a context-free and determinist language. So the whole language can be defined in terms of (recursive) PEG rules.

The PEG primitive constructs available in pest are:

• Matching against a lexeme, like "foo": this rule will recognize any string that is "foo".
• Matching against a range of char, like 'a' .. 'z': this will recognize any char in the range, like "a", "d" or "z".
• Matching against another rule, simply by using its name.
• Matching a sequence of rules, like a ~ b: this rule will be matched if it can match the a rule followed by the b rule; "foo" ~ 'a' .. 'z' will recognize "foot", "food", "fooz" but also "foo r" – this whitespace behavior is explained below – etc.
• Matching either a rule or another (alternative), like a | b: this rule will match either a if it succeeds or b if a fails and b succeeds or none otherwise. "foo" | 'a' .. 'z' will be matched with "foo" and "a" or "f".
• Optional matching with the ? suffix operator, like a?: this will match a if it succeeds or will just ignore its failure if it fails, making it optional. For instance, "hello"? ~ "world" will match both "hello world" and "world".
• Parenthesis can be used to group rules and reason on them as a whole, like (a ~ b).
• Repetitions:
  • The Kleene star (matches zero or many), like a*: this rule matches zero or more times the a rule. For instance, ('0' .. '9')* will match "0" and "314" but will also match "".
  • The Kleene plus (matches one or many), like a+: this rule matches one or more times the a rule. For instance, ('0' .. '9')+ will match "0" and "314" but will not match "" because it expects at least one digit.
  • The {min, max} notation. The rule a{0,} is akin to a*: it must be matched at least 0 times and at maximum infinite times. The rule a{,3} must be matched between 0 and 3 times and the rule a{1, 12} must be matched between 1 and 12 times.

Additionally, pest provides a notation to add rule modifiers:

• A simple rule is written rule_name { definition }, like number = { ASCII_DIGIT+ }.
• ~, * and + rules get interleaved with two special rules if defined:
  • WHITESPACE, defining how to eat a single whitespace.
  • COMMENT, defining how to eat a comment.
  • Those rules are interleaved as (WHITESPACE | COMMENT)* so that number = { ASCII_DIGIT+ } gets actually rewritten as number = { (ASCII_DIGIT | (WHITESPACE | COMMENT)*)+ }.
• Because of that last rule, sometimes we don’t want that to happen. In the case of the number rule defined above, both "324" and "3 2 4" will get matched if we defined WHITESPACE to eat " ". In order to fix this, the @ modifier can be prepended to the rule definition:
  • number = @{ ASCII_DIGIT+ }
  • This rule will not get interleaved at all and is atomic.
  • Easy-to-remember: @ for @tomic. :)
• The _ modifier can be used to mute a rule. For instance, eating whitespaces will not provide you with any useful tokens. That’s why the WHITESPACE rule is defined as WHITESPACE = _{ " " }.
• There are some other modifiers, like $ and ! but we’re not interested in them as they’re very specific.

So, basically, you write a (long) list of PEG rules in a file, give that file to Rust via a proc-macro derive, et voila!

#[derive(Parser)]
#[grammar = "path/to/grammar.pest"]
struct Parser;

It’s that simple.

Facing issues

PEG is really cool to use… but there are caveats. For instance, PEG / pest cannot express left-recursive rules. To understand this, take this rule:

foo = { a | b ~ foo* }

This rule is correct and will allow you to match against "a" or "b" or even "bbbbbbbbb" and "bbbbbbbba". However, the following one is left-recursive and won’t be able to be compiled:

foo = { a | foo* ~ b }

As you can see, the second alternative is left-recursive. Imagine matching against "a": the first alternative fires, everything is great. Now match against "b". The first alternative fails so pest tries the second one, but in order to take the second one, it needs to try at least once foo (the foo*) to see whether it fails or not. If it fails, it will then ignore and try to eat a "b". If it succeeds, it will try to fire the foo rule again. However, when it tries foo for the first time, it will try the first alternative again, a, then will fail, then will try foo*, then a, then foo*, then… You see the pattern.

Left-recursive rules are then forbidden so that we can escape that situation. PEGs need to be unambiguous and the rules (especially alternatives) are tested in order. You will have to unroll and optimize those rules by hand. In our case, we can rewrite that rule in a PEG-compliant way:

foo = { (a | b)+ }

An issue I had while writing the PEG of GLSL450 was with the expression rule (among a loooot of others). Khronos’ specifications are written with left-recursive rules pretty much everywhere and this is the one for expressions:

expression:
  assignment_expression
  expression COMMA assignment_expression

Read it as “An expression is either an assignment expression or an expression with a comma followed by an assignment expression”. This actually means that the second alternative cannot be constructed without the first one – because it’s recursive! So you must start with an assignment_expression. Then you can have the second rule applied recursively, like so (parenthesis just for convenience to show the left-recursion):

((((assignment_expression) COMMA assignment_expression) COMMA assignment_expression) COMMA assignment_expression)

Etc., etc. If you remove the parenthesis, you get:

assignment_expression COMMA assignment_expression COMMA assignment_expression COMMA assignment_expression

Which you should now be able to write with a PEG rule easily! Like so:

expression = { assignment_expression ~ (COMMA ~ assignment_expression)* }

Way better and without left-recursion! :) So I spent pretty much a whole afternoon trying to remove left-recursions (and some rules were really nasty). I even have one remaining rule I’ll have to cut like a surgeon later to make it fully available (I had to do the same thing with nom; it’s the rule allowing postfix expressions to be used as function identifiers; issue here).

Is it really a parser?

Then I started to play with those generated Rule types… wait, what?! The generated Rule type? Ok so that was my first surprise: the grammar knows how the rules are (deeply) nested but pest outputs a single Rule type with all the rules laid down as flat variants for that Rule! This was at first very confusing for me as I thought I’d be visiting freely through the AST – because this is what a grammar actually defines. Instead, you must ask your Parser type which rule you want to match against. You get a Pairs, which is an iterator over Pairs.

A Pair defines a single token that is defined by its starting point and ending point (hence a pair… yeah I know, it’s confusing). A Pair has some methods you can call on it, like as_str() to retrieve its string slice in the (borrowed) input of your parser. Or into_inner(), giving you a Pairs that represent the matched inner tokens, allowing you to eventually visit through the tree of tokens.

I have two problems with that.

My unreachable goals

First, because pest doesn’t fully use the grammar information at type-level, you lose the one crucial information: the actual topology of your grammar in the type system. That means that every time you will ask for a given Pair, you will have to call as_rule() on it an pattern-match on the whole list of variants that compose your grammar! In all situations, you will only need to match against a very few of them and will discard every others. And how do you discard them? – you know those are impossible because the very definition of the grammar? You use unreachable!(), which I find almost as unsafe and ugly as using unimplemented!(). I know unreachable!() is required in certain situations, but having it spawn in a parser using the public API of pest makes me gnash my teeth. Example of code I’m currently writing:

fn parse_type_specifier_non_array<'a>(pair: Pair<'a>) -> Result<syntax::TypeSpecifierNonArray, String> {
  let inner = pair.into_inner().next().unwrap();

  match inner.as_rule() {
    Rule::struct_specifier => {
      // …
    }

    Rule::identifier => {
      let identifier = inner.as_str();

      match identifier {
        "void" => Ok(syntax::TypeSpecifierNonArray::Void),
        "float" => Ok(syntax::TypeSpecifierNonArray::Float),
        "double" => Ok(syntax::TypeSpecifierNonArray::Double),
        // …
        _ => Ok(syntax::TypeSpecifierNonArary::TypeName(identifier.to_owned())
      }
    }

    _ => unreachable!()
  }
}

And I reckon I will find that pattern a lot in my next few hours / days of writing those functions.

Lexing and parsing are two different concepts

That parse_type_specifier_non_array function of mine also pinpointed another issue I had: initially, I wrote that logic in the type_specifier_non_array rule in the PEG grammar, like:

type_specifier_non_array = {
  "void" |
  "float" |
  // …
  identifier
}

And quickly came to the realization that the identifier alternative would get muted very often by the lexemes alternatives. Imagine two strings, "int x = 3;" and "interop x = …;". The first type will get the right TypeSpecifierNonArray::Int AST representation and the second string… will get the same because the "int" rule will fire first, leaving some unmatched text without any sense ("erop x = …;").

What that means is that we cannot express this rule this way with PEG. I’ve been told pest should now support the ! operator that can be used to encode something that must not be parsed. But that would just slightly hide the problem: there is no way in the PEG rules to actually do parsing transformation. What pest really is here is a lexer: it generates tokens. Yes, it does place them in a tree (token tree), but they all remains tokens (strings). And that is when I thought about the difference between pest and nom

Pest, nom… let’s explain

nom is a parser combinator. That means you can build bigger parsers by combining small parsers. The correct term to talk about nom is that it’s a scannerless parser: it doesn’t require to generate tokens prior to do parsing and prefers to do both at the same time. nom parsers are typically implemented using macros like preceded!, delimited!, take_until!, tag!, value! and do_parse!, allowing for matching (lexing) slices of bytes / chars and parsing them to actual values with the type of your choice.

However, pest relies on a PEG file, representing the formal grammar of a language to tokenize. That lexer phase takes place and has to be able to tokenize the whole input before giving hand back. I’m not sure when I say this (but I’m pretty convince it’s the case): pest doesn’t support streaming input, since it needs to eat the special rule EOI – End Of Input – or eat a rule error (to succeed with the previous rule or propagate the error upwards) before returning. nom can be used to eat streams of bytes, though.

And then, you have two choices with pest:

1. Either you decide to expose the tokens as a token tree, in which case the AST contains string slices, completely left to be parsed.
2. Either, like me, you have your own AST representation and you will have to write the actual parser over pest.

I’m currently experimenting with (2.). The type_specifier_non_array rule is one of the biggest one in my grammar so maybe I’ve already done the worst case but I’m fearing I’ll have long nights of coding before ending up with a benchmark pest vs. nom.

Call to contributions

In the meantime:

• I’ve written a very simple SPIR-V transpiler (that uses shaderc behind the hood). If you’re looking for an easy contribution, I’m looking for someone to test the feature branch holding the implementation, cleaning it, writing tests for it and merging it to master. Issue here.
• I’m looking for a way to encode #define and other preprocessors pragmas. I’m taking contributions (implementations, ideas) to fix that problem. Issue here.
• If you want to start working on refactoring the AST a bit (it was designed based on the Khronos grammar rules… which are quite ugly :P), please feel free to open an issue. I will eventually do it anyway sooner or later, but you know… :)
• A lot of the types in the syntax module (the AST types) don’t have new methods. Those methods are important to me as they enable to bypass some limitation from the current glsl-quasiquote implementation that doesn’t allow variable interpolation.
• Anything else! Feel free to contribute!

Thanks for having read through, and keep the vibes!

The latest version of luminance has one of the two features. UBO were added and SSBO will follow for the next version, I guess.

What is UBO?

UBO stands for Uniform Bbuffer Object. Basically, it enables you to create uniform blocks in GLSL in feed them with buffers. Instead of passing values directly to the uniform interface, you just write whatever values you want to to buffers, and then pass the buffer as a source for the uniform block.

Such a technique has a lot of advantages. Among them, you can pass a lot of values. It’s also cool when you want to pass values instances of a structure (in the GLSL source code). You can also use them to share uniforms between several shader programs as well as quickly change all the uniforms to use.

In luminance, you need several things. First thing first, you need… a buffer! More specifically, you need a buffer Region to store values in. However, you cannot use any kind of region. You have to use a region that can hold values that will be fetched from shaders. This is done with a type called UB a. A buffer of UB a can be used as UBO.

Let’s say you want to store colors in a buffer, so that you can use them in your fragment shader. We’ll want three colors to shade a triangle. We need to create the buffer and get the region:

colorBuffer :: Region RW (UB (V3 Float)) <- createBuffer (newRegion 3)

The explicit type is there so that GHC can infer the correct types for the Region. As you can see, nothing fancy, except that we just don’t want a Region RW (V3 Float but Region RW (UB (V3 Float)). Why RW?

Then, we’ll want to store colors in the buffer. Easy peasy:

writeWhole colorBuffer (map UB colors)

colors :: [V3 Float]
colors = [V3 1 0 0,V3 0 1 0,V3 0 0 1] -- red, green, blue

At this point, colorBuffer represents a GPU buffer that holds three colors: red, green and blue. The next part is to get the uniform interface. That part is experimental in terms of exposed interface, but the core idea will remain the same. You’re given a function to build UBO uniforms as you also have a function to build simple and plain uniforms in createProgram:

createProgram shaderList $ \uni uniBlock -> {- … -}

Don’t spend too much time reading the signature of that function. You just have to know that uni is a function that takes Either String Natural – either a uniform’s name or its integral semantic – and gives you mapped U in return and that uniBlock does the same thing, but for uniform blocks instead.

Here’s our vertex shader:

in vec2 co;
out vec4 vertexColor;

// This is the uniform block, called "Colors" and storing three colors
// as an array of three vec3 (RGB).
uniform Colors {
  vec3 colors[3];
};

void main() {
  gl_Position = vec4(co, 0., 1.);
  vertexColor = vec4(colors[gl_VertexID], 1.);
}"

So we want to get a U a mapped to that "Colors" uniform block. Easy!

(program,colorsU) <- createProgram shaderStages $ \_ uniBlock -> uniBlock "Colors"

And that’s all! The type of colorsU is U (Region rw (UB (V3 Float))). You can then gather colorBuffer and colorsU in a uniform interface to send colorBuffer to colorsU!

You can find the complete sample here.

Finally, you can augment the type you can use UB with by implementing the UniformBlock typeclass. You can derive the Generic typeclass and then use a default instance:

data MyType = {- … -} deriving (Generic)

instance UniformBlock MyTpe -- we’re good to go with buffer of MyType!

luminance, luminance-samples and Stackage

I added luminance and luminance-samples into Stackage. You can then find them in the nightly snapshots and the future LTS ones.

What’s next?

I plan to add stencil support for the framebuffer, because it’s missing and people might like it included. I will of course add support for SSBO* as soon as I can. I also need to work on cheddar but that project is complex and I’m still stuck with design decisions.

Thanks for reading my and for your feedback. Have you great week!

Context & problem

The way it typically works is by writing the GLSL code in a hard-coded string, or a file that is dynamically loaded at runtime by your application (some people even pre-compile GLSL into a binary form, but it doesn’t change the fact that the binary has to be brought to the GPU at runtime). The overall implication of all this is that the shader is represented via an opaque String (or binary like Vec<u8>) in your application.

A couple of examples of interfaces to handle shaders, using wgpu and a crate of mine, luminance:

• wgpu::ShaderSource
• luminance::shader::ProgramBuilder::from_strings

As you can see, dealing with shader sources implies a string interface, because that’s basically code that needs to be compiled by your GPU driver (done at runtime). That has several issues:

• There is no way to inspect the content of the shader to use its inputs, outputs, environment variables, etc. That leads to a lot of code duplication, which is just String duplication all over the place.
• Your application might compile and run, you are not sure that your shaders are correctly written, so you have to write a runtime checker for your shader, that needs to go through all the shaders in use in your application. Tedious, and error-prone.
• You have to learn a shading language. Most of the time, GLSL should be enough, but GLSL is old, and not very fun to work with.
• You will have to write the same code over and over and over. For instance, in GLSL, there is no definition of π, so you will have to write its definition whenever you need it. That will quickly lead you to write some combinator code to inject sub strings containing such definitions and it will be a nightmare.
• It’s very weakly typed. A String doesn’t allow you to be sure that shader is compatible with the graphics pipeline. Being the author of luminance, that is a massive flaw to me. As you might know, the typing in luminance is pretty advanced (phantom typing, type families, type states, etc.), so being stuck with String is not a good situation.

Introducing shades

I introduced shades a couple of years ago without going public about it. The reason for that was that it was not completely ready for people to use. Of course you could have given a try (and fundamentally, it hasn’t changed much), but the syntax was going to drive people off right away. The idea of shades is to write shaders directly in Rust. Instead of using String to represent a shader stage, you use Stage<Inputs, Outputs, Environment>. That gives you a first visible advantage: typing. In shades, you don’t have to declare your inputs, outputs nor environment. For instance, compare the following GLSL code with its shades counterpart:

uniform float time;
uniform vec2 resolution;

Whenever a shader stage has to use time or resolution, they will have to declare those two lines at the top of their sources. With shades:

#[derive(Debug)]
struct Env {
  time: f32,
  resolution: V2<f32>,
}

#[derive(Debug)]
struct EnvExpr {
  time: Expr<f32>,
  resolution: Expr<V2<f32>>,
}

impl Environment for Env {
  type Env = EnvExpr;

  fn env() -> Self::Env {
    EnvExpr {
      time: Expr::new_env(0),
      resolution: Expr::new_env(1),
    }
  }

  fn env_set() -> Vec<(u16, Type)> {
    vec![
      (0, <f32 as ToType>::to_type()),
      (1, <V2<f32> as ToType>::to_type()),
    ]
  }
}

When using a Stage<_, _, Env>, time and resolution will automatically be available, whenever you use them or not. This is even more interesting with procedural macro support in luminance for instance:

// the Environment and Semantics derive macro will generate all the above code for you, as well as the type family
#[derive(Debug, Environment, Semantics)]
struct Env {
  time: f32,
  resolution: V2<f32>,
}

So yes, shades is a bit more verbose at the Rust level, but I think it’s worth it because shaders are checked at compile-time (via rustc) and not at runtime anymore. Typing also allows a better composition and reusability.

Just to give you an idea, this is an old and outdated example taken from the repository to show you what it used to be:

let vertex_shader = StageBuilder::new_vertex_shader(
  |mut shader: StageBuilder<MyVertex, (), ()>, input, output| {
    let increment = shader.fun(|_: &mut Scope<Expr<f32>>, a: Expr<f32>| a + lit!(1.));

    shader.fun(|_: &mut Scope<()>, _: Expr<[[V2<f32>; 2]; 15]>| ());

    shader.main_fun(|s: &mut Scope<()>| {
      let x = s.var(1.);
      let _ = s.var([1, 2]);
      s.set(output.clip_distance.at(0), increment(x.clone()));
      s.set(
        &output.position,
        vec4!(input.pos, 1.) * lit![0., 0.1, 1., -1.],
      );

      s.loop_while(true, |s| {
        s.when(x.clone().eq(1.), |s| {
          s.loop_break();
          s.abort();
        });
      });
    })
  },
);

let output = shades::writer::glsl::write_shader_to_str(&vertex_shader).unwrap();

That snippet doesn’t do anything really logical; it’s just there to show you how things look like.

I wrote a couple of things with shades, and even though I like it, I have to admit that the Rust API is pretty hard to read, use and understand. I needed something better.

The new age of shades: shades-edsl

Then it struck me: why would that API need to be the one people use? It can remain public, but maybe we can build something above it to make it much easier to use. The initial idea of that API was to be an EDSL, but Rust has a lot of limitations (for instance, Eq methods, Ord methods, etc. return bool, while I would need them to return Expr<bool>). So… I came to the realization that the right way to do this would be to write a real EDSL: shades-edsl.

The idea of shades-edsl is super simple: remove everything that would make shades usable directly by a human, and build a procedural macro that transforms regular Rust code into the API from shades. Basically, generate the shades code inside the code of a procedural macro, which is what humans will use.

The way it works is pretty straight-forward to understand: you write your shading code in a shades! { … } block. Everything in that block is reinterpreted and replaced by shades symbols: builders, method calls, etc. etc.

For instance, the following:

let stage = shades! { VS |_input, _output, _env| {
  fn add(a: i32, b: i32) -> i32 {
    a + b
  }

  fn main() {
    // do nothing
  }
}};

Will be reinterpreted as:

let stage = shades::stage::StageBuilder::<_, _, _>::new_vertex_shader(…);

Where … is generated code (a lambda here). A couple of more example:

  // in a shades! block
  if cond {
    body_if
  } else {
    body_else
  }

is transformed into:

  __scope.when(cond, |__scope| {
    #body_if // body_if is also transformed
  }).or_else(|__scope| {
    #body_else
  });

Feature list

• Constant declarations: the regular Rust const declarations work and declare constant items in the shading code.
• Function declarations: two kind of declarations are supported:
  • Any kind of functions declared with fn will create function declarations and return a function handle (so that you can call the function).
  • A function called main will not return a function handle, but instead will inject the function declaration and will return the Stage. It is the only way to produce a Stage so you have the certainty that a Stage contains the main function.

How it works

shades-edsl is implemented as a procedural macros, shades!, which defines a shader stage. It’s basically a monadic computation (using shades::stage::StageBuilder behind the scene). Once you write your fn main() function, the builder simply generates the Stage object for you (using StageBuilder::main_fun). In terms of architecture, it’s a pretty simple one:

1. I use the syn crate to parse the content of the shades! invocation (TokenStream).
2. I then mutate the generated AST to optimize and inject some logic in your code.
3. I marshal the AST back to Rust by generating the calls to the shades API, and write the Rust code back to the TokenStream

Parsing the Rust code

Parsing the Rust code uses syn, a famous parsing crate used a lot by procedural macros. It was made to parse Rust-like code, but it has some interesting use cases. I’m used to writing procedural macros in luminance-derive for instance (#[derive()] annotations).

The idea is to take a Rust item and represent it as a data type. The important thing to know with syn is that it supports nice error message reporting, so you are advised to store non-meaningful information, like braces, parens, tokens, etc.

For instance:

let x: Type = 3;

We can represent such an item (a let declaration) with the following struct:

#[derive(Debug)]
pub struct VarDeclItem {
  let_token: syn::Token![let],
  name: syn::Ident,
  ty: Option<(syn::Token![:], syn::Type)>,
  assign_token: syn::Token![=],
  expr: syn::Expr,
  semi_token: syn::Token![;],
}

syn::Token! is a type macro that resolves to the right type name for the given symbol.

Parsing in syn uses the Parse trait, and is more intimidating than hard to use. This is the whole parser for VarDeclItem:

impl Parse for VarDeclItem {
  fn parse(input: syn::parse::ParseStream) -> Result<Self, syn::Error> {
    let let_token = input.parse()?;
    let name = input.parse()?;

    let ty = if input.peek(Token![:]) {
      let colon_token = input.parse()?;
      let ty = input.parse()?;
      Some((colon_token, ty))
    } else {
      None
    };
    let assign_token = input.parse()?;
    let expr = input.parse()?;
    let semi_token = input.parse()?;

    Ok(Self {
      let_token,
      name,
      ty,
      assign_token,
      expr,
      semi_token,
    })
  }
}

ParseStream is the current state of the input stream. As you can see with the type of parse(), it will return the Self type or an error, so we can call input.parse()? inside the implementation if type inference knows what the type is, and that the type implements Parse. In our case, syn::Token![let] and syn::Ident do implement Parse, so we can parse them in two simple lines:

    let let_token = input.parse()?;
    let name = input.parse()?;

Then, we need to look ahead to check whether there is a semicolon (:). If there is, then we can parse syn::Token![:] and syn::Type, as both already implement Parse. Otherwise, we simply assume None as type ascription:

    let ty = if input.peek(Token![:]) {
      let colon_token = input.parse()?;
      let ty = input.parse()?;
      Some((colon_token, ty))
    } else {
      None
    };

The rest is as simple as everything implements Parse as well:

    let assign_token = input.parse()?;
    let expr = input.parse()?;
    let semi_token = input.parse()?;

We have everything we need to return the parsed declaration:

    Ok(Self {
      let_token,
      name,
      ty,
      assign_token,
      expr,
      semi_token,
    })

Every Rust items are parsed like that. There are a couple of harder things. For instance, input can be split by parsing matched delimiters, resulting in two disjoint inputs, or some items will have to be delimited with punctuation (a token).

An example of disjoint input parsing while parsing if statements:

#[derive(Debug)]
pub struct IfItem {
  if_token: Token![if],
  paren_token: Paren,
  cond_expr: Expr,
  brace_token: Brace,
  body: ScopeInstrItems,
  else_item: Option<ElseItem>,
}

// …

impl Parse for IfItem {
  fn parse(input: syn::parse::ParseStream) -> Result<Self, syn::Error> {
    let if_token = input.parse()?;

    let cond_input;
    let paren_token = parenthesized!(cond_input in input);
    let cond_expr = cond_input.parse()?;

    let body_input;
    let brace_token = braced!(body_input in input);
    let body = body_input.parse()?;

    let else_item = if input.peek(Token![else]) {
      Some(input.parse()?)
    } else {
      None
    };

    Ok(Self {
      if_token,
      paren_token,
      cond_expr,
      brace_token,
      body,
      else_item,
    })
  }
}

Here, we use the parenthesized! macro that parses a matching pair of (). Once it has finished, the input has advanced after the closing delimiter, but the second input (cond_input in our case) is scoped right after the opening delimiter and right before the closing one. That allows us to parse “inside” the parenthesis, which is a weird interface at first, but once you get used to it, it’s actually pretty smart and pretty fast. Notice how we parse the conditional expression using cond_input and not input here:

    let cond_input;
    let paren_token = parenthesized!(cond_input in input);
    let cond_expr = cond_input.parse()?;

Same thing with {} and the braced! macro:

    let body_input;
    let brace_token = braced!(body_input in input);
    let body = body_input.parse()?;

An even more interesting example: parsing function definitions:

#[derive(Debug)]
pub struct FunDefItem {
  fn_token: Token![fn],
  name: Ident,
  paren_token: Paren,
  args: Punctuated<FnArgItem, Token![,]>,
  ret_ty: Option<(Token![->], Type)>,
  brace_token: Brace,
  body: ScopeInstrItems,
}

Here, args is a punctuated sequence of FnArgItem, delimited with ,. The parser is as follows:

impl Parse for FunDefItem {
  fn parse(input: syn::parse::ParseStream) -> Result<Self, syn::Error> {
    let fn_token = input.parse()?;
    let name = input.parse()?;

    let args_input;
    let paren_token = parenthesized!(args_input in input);
    let args = Punctuated::parse_terminated(&args_input)?;

    let ret_ty = if input.peek(Token![->]) {
      let arrow_token = input.parse()?;
      let ret_ty = input.parse()?;
      Some((arrow_token, ret_ty))
    } else {
      None
    };

    let body_input;
    let brace_token = braced!(body_input in input);
    let body = body_input.parse()?;

    Ok(Self {
      fn_token,
      name,
      paren_token,
      args,
      ret_ty,
      brace_token,
      body,
    })
  }
}

The argument part uses parenthesized! to parse the all arguments definitions, and then, with a single argument parser (identifier plus type: ident: Type), we can simply ask to parse many by using comma punctuation. This is done with parse_terminated:

    let args_input;
    let paren_token = parenthesized!(args_input in input);
    let args = Punctuated::parse_terminated(&args_input)?;

Parsing with syn is a bit weird at first (I’m used to nom because of glsl), but in the end, I think it’s a pretty funny and interesting interface. There is no combinator such as alternative parser selection, but that’s probably for the best, because the peek / look ahead interface forces you to write fast parsers. I really like it.

Mutating the AST

Mutating the AST is a top-down operation that consists in transforming types and expressions. The goal is to lift items up the shades EDSL. A function such as:

fn add(a: i32, b: i32) -> i32

Needs to be representable in the shades AST. For this reason, a, b and the return type have to change types. Changing the type implies going from T to Expr<T>. That operation is done in a mutate(&mut self) method on each syntax items parsed from the previous stage, and each of mutate invocation might call mutate on items they contain (such as punctuated items, collections of instructions / statements, etc.).

The only interesting part to discuss here is probably how we can lift values in complex expressions such as a + (b * c). This is done with the concept of mutable visitors, defined in syn with the visit-mut feature gate. A mutable visitor is simply an object that implements a trait (VisitMut), which defines one method for each type of items in the AST that might exist. For instance, there is visit_expr_mut(&mut self, e: &mut syn::Expr) and a visit_type_mut(&mut self, e: &mut syn::Type). All visit_* methods have a default implementation doing nothing, so that you are left with implementing only the ones that matter for you.

An example of what I do with types:

struct ExprVisitor;

impl VisitMut for ExprVisitor {
  fn visit_type_mut(&mut self, ty: &mut Type) {
    *ty = parse_quote! { shades::expr::Expr<#ty> };
  }
}

parse_quote! is a syn macro that is akin to quote! from quote, but can infer the return type to parse to the right type. Here, the returned type is inferred to be syn::Type.

An interesting thing with shades-edsl: because users will provide their inputs, outputs and environment types in the types of Stage, we do not want to wrap those in Expr, because they already contain Expr values, as seen earlier. For this reason, the syntax of types of arguments was augmented with the possibility to add a dash (#) in behind the types. If such a symbol is found, the type is assumed unlifted and shouldn’t be lift. For instance:

let a: i32 = …; // will become Expr<i32>
let b: #Foo = …; // will remain Foo

Generating the shades code

Generating the shades AST is just a matter of traversing the parsed and mutated AST and using the quote crate and its quote! macro to write the Rust code we want. The only missing part is how to bootstrap a StageBuilder, which is done with some more parsing. Invocation looks like this:

  let stage = shades! { vertex |input: TestInput, output: TestOutput, env: TestEnv| {

The first keyword is vertex here, but it could be fragment, geometry or any kind of shader stage (that needs to be documented). Then, you have a lambda. I chose that syntax because a shader stage can be imagined as a function of its input, output and environment. I hesitated with returning the output, but it would make things harder for some stages (i.e. geometry shaders), where they can write to the same output several times. In that lambda, every type is automatically marked as unlifted (so input: TestInput and input: #TestInput are the same).

Once transformed, this single line is akin to something like this:

shades::stage::StageBuilder::new_vertex_shader(|mut __builder: shades::stage::StageBuilder::<#user_in_ty, #user_out_ty, #user_env_ty>, #input, #output| {

Everything else works the same way. Some fun example:

The generated code when the main function is found:

    if name.to_string() == "main" {
      let q = quote! {
        // scope everything to prevent leaking them out
        {
          // function scope
          let mut __scope: shades::scope::Scope<()> = shades::scope::Scope::new(0);

          // roll down the statements
          #body

          // create the function definition
          use shades::erased::Erased as _;
          let erased = shades::fun::ErasedFun::new(Vec::new(), None, __scope.to_erased());
          let fundef = shades::fun::FunDef::<(), ()>::new(erased);
          __builder.main_fun(fundef)
        }
      };

      q.to_tokens(tokens);
      return;
    }

If items:

impl ToTokens for IfItem {
  fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
    let cond = &self.cond_expr;
    let body = &self.body;

    let q = quote! {
    __scope.when(#cond, |__scope| {
      #body
    }) };

    q.to_tokens(tokens);

    match self.else_item {
      Some(ref else_item) => {
        let else_tail = &else_item.else_tail;
        quote! { #else_tail }.to_tokens(tokens);
      }

      None => {
        quote! { ; }.to_tokens(tokens);
      }
    }
  }

Else tail items, which allows to add an if again (else if) or stop to else only. You will notice in ToTokens implementation of IfItem that there is no ; added at the end of the .when() call unless there is no else following, and that rule is kept enforced in ToTokens for ElseTailItem as well. See, static analysis at compile-time!:

impl ToTokens for ElseTailItem {
  fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
    match self {
      ElseTailItem::If(if_item) => {
        if_item.to_tokens_as_part_of_else(tokens);
      }

      ElseTailItem::Else { body, .. } => {
        let q = quote! {
          .or(|__scope| { #body });
        };

        q.to_tokens(tokens);
      }
    }
  }
}

Writers

Once you get a Stage, you can use a writer to output a String, so that shades is compatible with any kind of library / framework / engine that expects a string-based shader source.

For example, for GLSL:

  let output = shades::writer::glsl::write_shader_to_str(&vertex_shader).unwrap();

Interaction with luminance

Eh, I wrote both crates, so obviously luminance has / will have a special support of shades. Remember the definition of Environment above? It’s similar to Inputs and Outputs, too. luminance-derive already provides some derive macros to automatically implement some traits, and it will provide a support to implement Inputs, Outputs and Environment as well, without having to think about the indexes.

Caveats and alternative work

Of course, if something is not implemented correctly (a bug in shades-edsl, a bug in shades), debugging the output shaders will be harder, because everything is generated (names included) on the target side. It’s something to keep in mind.

You should also have a look at some similar yet different approaches:

• rust-gpu from EmbarkStudios. It’s a similar project but instead of parsing Rust code, they wrote a compile chain (that you need to install via rustup) and compile your code with. It’s an interesting point but I wanted something more typed with a more seamless integration to the rest of my ecosystem (i.e. luminance).
• wgsl, a new shading language for the WebGPU.
• glsl-quasiquote: you can write GLSL code in it and get it parsed at compile-time. However, it will use the glsl crate, which is currently a parser only, and it will not do any kind of semantic analysis. Another crate has to be written for that, and it doesn’t exist to my knowledge (and I won’t write it because it’s a lot of work and I don’t think it’s the right approach, unless you want to write a GLSL compiler, which I don’t).

Keep the vibes!

Reddit discussion

1. The first commit of luminance was made in 2016, as I migrated it away from its Haskell version, which first commit was made in 2015. Since then, my knowledge of programming, both Haskell and Rust, but also in general has enhanced quite a lot.
2. The current design has some flaws, both in terms of usability and maintainability.

About the first point, I had a look at code that barely changed since I wrote it in 2016, and I’m not completely satisfied with it anymore. Lots of things happened ever since: I have a sharper vision of how things should be done, Rust itself has changed quite a lot (back in 2016, Rust 1.0 was just released!), we have more type system features that, back then, I was lacking, etc.

About the second point, some issues in the current version of luminance (v0.47 as writing this blog article) are complex to solve, such as the Drop problem. Other parts of the API are insanely complex, like the TessBuilder related code.

I want all that to change, so I started working on a completely new graphics crate, just to see what kind of interface I could come up with. And I came up with something much, much easier. So I faced a dilemma: should I release that other crate and give up on luminance… or should I just port all the new knowledge and ideas from that crate into luminance?

Well, I have decided to keep luminance around and update it. It is going to take time, because luminance is an ecosystem of many crates, it has lots of examples (which is great to ensure that its features are still working correctly once I start redesign it) and because some features are obviously entangled. However, I think it’s worth it, because even though luminance is not as famous or widely used as wgpu, it has a special place in the Rust Graphics community.

So I’m going to blog about the redesign of luminance and it’s going to be a blog article series. I wanted to start with a very new exciting feature that I have been wanting for a very long time: compatible vertex types.

The vertex compatibility problem

When you’re like me and are obsessed with tracking as much information as possible at compile-time, you start imagining lots of features and ways to prevent people from doing things. Preventing and forbidding is actually much more complex than allowing something. Think about it like this: assembly allows for everything and is not a complex language. It has zero constructs, besides opcodes. However, as you add more constructs and abstractions, those abstractions restricts the application domain; they forbid usage, in a constrained way. There’s a reason why, in Haskell, we use the term Contraint — which is called, basically, trait bound in Rust.

The way luminance allows a programmer to render objects, which must have a vertex type V that must implement Vertex. luminance-derive eases the process of implementing lots of traits from luminance. For instance:

#[repr(C)]
#[derive(Clone, Debug, Vertex)] // < notice the Vertex derive here
pub struct MyVertex {
  position: Vector3<f32>,
  normal: Vector3<f32>,
  color: Vector3<u8>,
  weight: Vector3<f32>,
}

This is great, because the user just has to focus on writing types and just using them. For vertex objects, which can be imagined as big arrays / buffers of MyVertex here, there are types and functions allowing to basically render such object, and those render functions expects MyVertex. However, rendering is a multi-stage process. As you may know, the graphics pipeline contains different steps, and among the first ones, you have a vertex shader, which is responsible in mapping vertices (to transform them, for instance). In luminance, vertex shaders are strongly-typed with the kind of vertices they expect. That is to prevent a user from using a vertex shader that expects some vertex attributes that a vertex object doesn’t have. Imagine that we write a vertex shader that expects a position and a normal but our vertex object, which uses OtherVertex vertices, only has position. That would result in probably some visual glitches or just a black screen.

So, we want to have something like this pseudocode:

type VertexShader<V>; // accept only vertex type V
type RenderVertexObjects<W>; // render only vertex type W

If we want to have a fully typed graphics pipeline, we must have V = W. However, that is going to be very annoying. Imagine a vertex shader that only needs position, normal and color. Something like:

#[repr(C)]
#[derive(Clone, Debug, Vertex)]
pub struct ShaderVertexInput {
  position: Vector3<f32>,
  normal: Vector3<f32>,
  color: Vector3<u8>,
}

This is a different type than MyVertex, so if we try to render our MyVertex vertex objects with a vertex shader that works on ShaderVertexInput, it will get a type mismatch at compile-time. The only way to fix that is to create a copy of the shader program that works with MyVertex and ignore the weight field. Meh. Waste of resources and duplication. Everything we don’t want.

When you look at it, the vertex shader is going to use position, normal and color, but it doesn’t have to know there are other vertex attributes. So it should be able, in theory, to work with MyVertex, since MyVertex has position, normal and color…

The solution

One solution to fix the problem is to introduce a trait, CompatibleVertex, that we will use on the vertex shader code. The vertex shader still has its ShaderVertexInput type, but it will not require vertex objects to use that type. Instead, it will require vertex objects to use V and will require ShaderVertexInput: CompatibleVertex<V>. What it means is that ShaderVertexInput must be included in V. Said otherwise, V must have all of ShaderVertexInput’s fields (but it can have more).

pub trait CompatibleVertex<V> {}

Now the big question: how do we implement CompatibleVertex for a given concrete vertex type? Well, in the previous version of luminance, that used to be implemented manually by users of luminance. It was both unsafe and not really practical, so I just removed the concept (and luminance in version v0.47 and less is subject to the problem I described above, where you can render a vertex object which vertex type is not compatible with what the shader expects).

Const generics to the rescue

Since rustc-1.51, const generics can be used at compile-time. The feature allows to manipulate integers at compile-time. For instance:

pub struct Array<const N: usize> {
  // …
}

Here, N is a const generics, and you use it with types like Array<3> or Array<14>. However, that’s currently (rust-1.63) all you can do with a stable compiler… but we can do much more with a nightly compiler.

There is a feature called adt_const_params that allows using more types, and one type that is very important is &'static str. Yes, you heard right. Constant strings. We can write something like this:

#![allow(incomplete_features)] // as of rustc-1.65 nightly, this is still required
#![feature(adt_const_params)]

fn hello<const N: &'static str>() {
  println!("Hello {}!", N);
}

fn main() {
  hello::<"world">();
}

That doesn’t seem like much, but this small change is going to save so many frustration in luminance, and fix our compatible vertex problems.

Applying adt_const_params to CompatibleVertex

What we basically want for one vertex type to compatible with another (i.e. one is included into the other) is to ensure that the all the fields of one are present in the other. Let’s recall our vertex type definitions and trait:

#[repr(C)]
#[derive(Clone, Debug, Vertex)]
pub struct MyVertex {
  position: Vector3<f32>,
  normal: Vector3<f32>,
  color: Vector3<u8>,
  weight: Vector3<f32>,
}

#[repr(C)]
#[derive(Clone, Debug, Vertex)]
pub struct ShaderVertexInput {
  position: Vector3<f32>,
  normal: Vector3<f32>,
  color: Vector3<u8>,
}

pub trait CompatibleVertex<V> {}

We can write a HasField trait like this:

pub trait HasField<const NAME: &'static str> {
  type FieldType;
}

And now, we can implement that trait for all the fields of our vertex types:

// for MyVertex
impl HasField<"position"> for MyVertex {
  type FieldType = Vector3<f32>;
}

impl HasField<"normal"> for MyVertex {
  type FieldType = Vector3<f32>;
}

impl HasField<"color"> for MyVertex {
  type FieldType = Vector3<u8>;
}

impl HasField<"weight"> for MyVertex {
  type FieldType = f32;
}

// for ShaderInputVertex
impl HasField<"position"> for ShaderInputVertex {
  type FieldType = Vector3<f32>;
}

impl HasField<"normal"> for ShaderInputVertex {
  type FieldType = Vector3<f32>;
}

impl HasField<"color"> for ShaderInputVertex {
  type FieldType = Vector3<u8>;
}

Now, we can write a more meaningful implementor for CompatibleVertex and ShaderInputVertex:

impl<V> CompatibleVertex<V> for ShaderInputVertex where
  V: HasField<"position", FieldType = Vector3<f32>>
    + HasField<"normal", FieldType = Vector3<f32>>
    + HasField<"color", FieldType = Vector3<u8>>
{
}

Because MyVertex implements the three HasField trait bounds required, it can be used, as well as ShaderInputVertex.

Obviously, because luminance-derive is a thing, people will never have to write any of those implementors. Actually, deriving Vertex will do two things (besides what it already does) for a given vertex type:

• Provide all the HasField implementors for all of its field.
• Provide the universal CompatibleVertex implementor.

What it means is that, as soon as you start using #[derive(Vertex)], you will automatically have compatible vertex types behind the scenes working for you.

Conclusion

That feature is already, by itself, worth requiring a nightly compiler, as it brings the exact kind of type safety I want for my code. And since I started with const generics strings, the next blog article will be about the redesign of vertex objects (called Tess in the current version of luminance), since, you might have guessed, it will use const generics strings to upload vertex data per-attribute, and map / update them.

Thanks for having read, and keep the vibe!

The thing is… Times change. The more it passes, the more I become mature in what I do in the Haskell community. I’m a demoscener, and I need to be productive. Writing a whole 3D engine for such a purpose is a good thing, but I was going round and round in circles, changing the whole architecture every now and then. I couldn’t make my mind and help it. So I decided to stop working on that, and move on.

If you are a Haskell developer, you might already know Edward Kmett. Each talk with him is always interesting and I always end up with new ideas and new knowledge. Sometimes, we talk about graphics, and sometimes, he tells me that writing a 3D engine from scratch and release it to the community is not a very good move.

I’ve been thinking about that, and in the end, I agree with Edward. There’re two reasons making such a project hard and not interesting for a community:

1. a good “3D engine” is a specialized one – for FPS games, for simulations, for sport games, for animation, etc. If we know what the player will do, we can optimize a lot of stuff, and put less details into not-important part of the visuals. For instance, some games don’t really care about skies, so they can use simple skyboxes with nice textures to bring a nice touch of atmosphere, without destroying performance. In a game like a flight simulator, skyboxes have to be avoided to go with other techniques to provide a correct experience to players. Even though an engine could provide both techniques, apply that problem to almost everything – i.e. space partitionning for instance – and you end up with a nightmare to code ;
2. an engine can be a very bloated piece of software – because of point 1. It’s very hard to keep an engine up to date regarding technologies, and make every one happy, especially if the engine targets a large audience of people – i.e. hackage.

Point 2 might be strange to you, but that’s often the case. Building a flexible 3D engine is a very hard and non-trivial task. Because of point 1, you utterly need to restrict things in order to get the required level of performance or design. There are people out there – especially in the demoscene world – who can build up 3D engines quickly. But keep in mind those engines are limited to demoscene applications, and enhancing them to support something else is not a trivial task. In the end, you might end up with a lot of bloated code you’ll eventually zap later on to build something different for another purpose – eh, demoscene is about going dirty, right?! ;)

Basics

So… Let’s go back to the basics. In order to include everyone, we need to provide something that everyone can download, install, learn and use. Something like OpenGL. For Haskell, I highly recommend using gl. It’s built against the gl.xml file – released by Khronos. If you need sound, you can use the complementary library I wrote, using the same name convention, al.

The problem with that is the fact that OpenGL is a low-level API. Especially for new comers or people who need to get things done quickly. The part that bothers – wait, no, annoys – me the most is the fact that OpenGL is a very old library which was designed two decades ago. And we suffer from that. A lot.

OpenGL is a stateful graphics library. That means it maintains a state, a context, in order to work properly. Maintaining a context or state is a legit need, don’t get it twisted. However, if the design of the API doesn’t fit such a way of dealing with the state, we come accross a lot of problems. Is there one programmer who hasn’t experienced black screens yet? I don’t think so.

The OpenGL’s API exposes a lot of functions that perform side-effects. Because OpenGL is weakly typed – almost all objects you can create in OpenGL share the same GL(u)int type, which is very wrong – you might end up doing nasty things. Worse, it uses an internal binding system to select the objects you want to operate on. For instance, if you want to upload data to a texture object, you need to bind the texture before calling the texture upload function. If you don’t, well, that’s bad for you. There’s no way to verify code safety at compile-time.

You’re not convinced yet? OpenGL doesn’t tell you directly how to change things on the GPU side. For instance, do you think you have to bind your vertex buffer before performing a render, or is it sufficient to bind the vertex array object only? All those questions don’t have direct answers, and you’ll need to dig in several wikis and forums to get your answers – the answer to that question is “Just bind the VAO, pal.”

What can we do about it?

Several attempts to enhance that safety have come up. The first thing we have to do is to wrap all OpenGL object types into proper types. For instance, we need several types for Texture and Framebuffer.

Then, we need a way to ensure that we cannot call a function if the context is not setup for. There are a few ways to do that. For instance, indexed monads can be a good start. However, I tried that, and I can tell you it’s way too complicated. You end up with very long types that make things barely unreadable. See this and this for excerpts.

Luminance

In my desperate quest of providing a safer OpenGL’s API, I decided to create a library from scratch called luminance. That library is not really an OpenGL safe wrapper, but it’s very close to being that.

luminance provides the same objects than OpenGL does, but via a safer way to create, access and use them. It’s an effort for providing safe abstractions without destroying performance down and suited for graphics applications. It’s not a 3D engine. It’s a rendering framework. There’s no light, asset managers or that kind of features. It’s just a tiny and simple powerful API.

Example

luminance is still a huge work in progress. However, I can already show an example. The following example opens a window but doesn’t render anything. Instead, it creates a buffer on the GPU and perform several simple operations onto it.

-- Several imports.
import Control.Monad.IO.Class ( MonadIO(..) )
import Control.Monad.Trans.Resource -- from the resourcet package
import Data.Foldable ( traverse_ )
import Graphics.Luminance.Buffer
import Graphics.Luminance.RW
import Graphics.UI.GLFW -- from the GLFW-b package
import Prelude hiding ( init ) -- clash with GLFW-b’s init function

windowW,windowH :: Int
windowW = 800
windowH = 600

windowTitle :: String
windowTitle = "Test"

main :: IO ()
main = do
  init
  -- Initiate the OpenGL context with GLFW.
  windowHint (WindowHint'Resizable False)
  windowHint (WindowHint'ContextVersionMajor 3)
  windowHint (WindowHint'ContextVersionMinor 3)
  windowHint (WindowHint'OpenGLForwardCompat False)
  windowHint (WindowHint'OpenGLProfile OpenGLProfile'Core)
  window <- createWindow windowW windowH windowTitle Nothing Nothing
  makeContextCurrent window
  -- Run our application, which needs a (MonadIO m,MonadResource m) => m
  -- we traverse_ so that we just terminate if we’ve failed to create the
  -- window.
  traverse_ (runResourceT . app) window
  terminate

-- GPU regions. For this example, we’ll just create two regions. One of floats
-- and the other of ints. We’re using read/write (RW) regions so that we can
-- send values to the GPU and read them back.
data MyRegions = MyRegions {
    floats :: Region RW Float
  , ints   :: Region RW Int
  }

-- Our logic.
app :: (MonadIO m,MonadResource m) => Window -> m ()
app window = do
  -- We create a new buffer on the GPU, getting back regions of typed data
  -- inside of it. For that purpose, we provide a monadic type used to build
  -- regions through the 'newRegion' function.
  region <- createBuffer $
    MyRegions
      <$> newRegion 10
      <*> newRegion 5
  clear (floats region) pi -- clear the floats region with pi
  clear (ints region) 10 -- clear the ints region with 10
  readWhole (floats region) >>= liftIO . print -- print the floats as an array
  readWhole (ints region) >>= liftIO . print -- print the ints as an array
  floats region `writeAt` 7 $ 42 -- write 42 at index=7 in the floats region
  floats region @? 7 >>= traverse_ (liftIO . print) -- safe getter (Maybe)
  floats region @! 7 >>= liftIO . print -- unsafe getter
  readWhole (floats region) >>= liftIO . print -- print the floats as an array

Those read/write regions could also have been made read-only or write-only. For such regions, some functions can’t be called, and trying to do so will make your compiler angry and throw errors at you.

Up to now, the buffers are created persistently and coherently. That might cause issues with OpenGL synchronization, but I’ll wait for benchmarks before changing that part. If benchmarking spots performance bottlenecks, I’ll introduce more buffers and regions to deal with special cases.

luminance doesn’t force you to use a specific windowing library. You can then embed it into any kind of host libraries.

What’s to come?

luminance is very young. At the moment of writing this article, it’s only 26 commits old. I just wanted to present it so that people know it exists will be released as soon as possible. The idea is to provide a library that, if you use it, won’t create black screens because of framebuffers incorrectness or buffers issues. It’ll ease debugging OpenGL applications and prevent from making nasty mistakes.

I’ll keep posting about luminance as I get new features implemented.

As always, keep the vibe, and happy hacking!

This article is a sequel to Let’s talk about C++ constructors. Even though not required, reading that article first might give you more information on the motivation and my state of mind regarding C++ and software development.

This time, I want to talk about C++ exceptions. But talking about exceptions for the sake of talking about them has very little value. Let’s instead talk about error handling.

Infallible pure functions

Imagine a function that takes some input, like a String, and outputs something else, like the length of the string. Such a function is pure: its output depends only on its arguments. It cannot have any side-effect nor return something else. It is also infallible as it can always return a valid length for all possible values it can be called with. Imagine the following C++ implementation:

size_t get_len(std::string const & s) {
  return s.length();
}

Even though C++ doesn’t have the concept of purity, let’s assume we can express the concept, just because it’s a powerful concept that we can apply to any language. The compiler will not know about it, but the way we design things does.

That function is pure and infallible. When you look at the signature, you see that it takes a read-only reference on a std::string , and returns a size_t. And yes, I know about noexcept. However, this specifier cannot be trusted. Consider:

#include <string>

void foo() {
  throw std::runtime_error("That should be seen by the compiler, right?");
}

size_t get_len(std::string const & s) noexcept {
  foo();
  return s.length();
}

int main() {
  std::string foo = "foo";
  get_len(foo);
  return 0;
}

Compile with (I’m running Archlinux):

g++ -std=c++2a -Wall -pedantic a.cpp

No compiler warning. Run it:

terminate called after throwing an instance of 'std::runtime_error'
  what():  That should be seen by the compiler, right?
zsh: abort (core dumped)  ./a.out

What that little snippet tells us is that even though get_len is annotated with noexcept… it can still throw. Not directly in its body, but functions it calls may throw. When I was introduced to that keyword, years ago, I was suspicious. Since C++ will throw exceptions for — erm — exceptional errors, such as out of memory errors, then… even a noexcept function can still throw errors. Then, because of that, noexcept cannot propagate downwards in your call stack. If A is noexcept and B may throw, then calling B from A is valid in C++.

noexcept is just a documentation keyword and an opportunity for your compiler to optimize your code. Your compiler can only emit warnings if you use the throw keyword directly in the body of the function that is marked noexcept. Also, it’s important to notice that, given the team you work in, or the project you work on, it’s possible to see the use of noexcept… like not at all. It’s all about convention; your compiler will not enforce that… which is a problem to me. It’s a problem because more freedom means more opportunities for people to make mistake. To forget about annotating a function with noexcept. Or, worse, it gives opportunities to people who just don’t care and want to rush, making reviewing their code more challenging than needed.

Fallible functions

In my previous article, I’ve been criticized for not explaining enough what I mean about exceptional errors and that it was a highly subjective point. I’ll try to explain more in this section.

Imagine that you want to implement a function that will perform a lookup. If it finds the key you give as argument, it will return the associated object. However, what to do when the key is not there? If you read a bit my previous article, you know that I would use a sum type to encode the error in the type system. But let’s do it the C++ way. Let’s use exceptions.

Object lookup(Key const & key);

If you look at that signature, you’ll notice an important point. There is no error handling annotation. Most of the time, people will follow some guidelines to put that information in the documentation directly. However, several points:

• What happens if a teammate of yours or even yourself – after some weeks / months – forgets about that documentation line?
• Because you might call that function from anywhere — even in noexcept code, as demonstrated in the previous section — how do you know, when reading the code, that a call to this function can throw?
• The last point is especially true when refactoring. Imagine that this function belongs to a block of code delimited with a try catch block. Do you assume the whole block as atomic? If so, do you lookup for the documentation of all of the functions called in that block? What happens if you move that function out of the block?

Now, that just assumes a flat block. But it’s easy to guess that you will have to do that for the whole stack of functions being called — i.e. as soon as you find a noexcept function in the stack… well nothing, you have to go on, since a throw might be hidden in a function deeper in the stack.

Most of the time, the replies I get about that topic are, either:

• “Just read the documentation”. That argument completely ignores the last part of my point above — i.e. do you really read the documentation of all the functions being directly or transitively called in a function? That seems insane. Also, you might argue that the documentation can say, at a function level N, that there is a throw at level N - k. However, that seems like an impossible task to maintain. You might forget to update the documentation if you stop throwing that exception or throw another object with a different type, etc.
• “Use better names. If you use a function that, in its name, expresses the idea that it might fail, it’s easier to refactor / use the function correctly”. That is true, even though you will always find someone abusing it and using it without a try catch block.
• “We don’t care about handling errors: we will just handle them at the top-level of the program / function call stack with a single try catch block”. That argument doesn’t survive five seconds as soon as you talk about, for instance, serialization or map lookups.

About the documentation and naming… it adds another problem: humans. We are fallible. You might work on a project that doesn’t document correctly. Or that doesn’t even have proper convention. Or several ones. When considering exceptions for error handling, I think it’s important to imagine what will happen in X months. After the codebase has become complex, large, with a lot of edge cases and possible errors. Maintainability should be a goal. No one enjoys having to read through the bodies of twenty functions to understand why their program crashed or why the GUI displays a pop-up with the content of an exception.

The sooner you can see an error, the better. If that sooner can be “compile-time”… why would you want to still push the error to the runtime? There are things I will never understand.

On the other side, consider sum types:

std::optional<Object> lookup(Key const & key);

Even though it’s still pretty bad to me because of how std::optional is made (have a look at my previous article), it has the advantage of being typed. No documentation is needed — but please do document to explain what can fail though — and your compiler can safely prevent you from doing bad things. Of course, this is limited by how you use the std::optional, as C++ doesn’t have pattern-matching. But I would like to reply to an argument I hear every now and then: it’s not because a better solution is not perfect that it should be discarded to stay on your legacy solution. Imagine that you have a tool X with several issues, {a, b, c, d}. Now imagine we suggest to switch to a new tool, Y, with issues {a, d} only. Yes, you still have two issues… but you have less. In the case of exceptions vs. a type-system, in the case of C++, yes, you can still call .value() on an empty std::optional and crash your program. But you don’t have the problem of hidden and untracked error handling. You can simply use exceptions for exceptional cases. Those cases that are not function boundaries nor edge cases. And yes, I do think that most of the standard C++ exceptions, such as std::invalid_argument, are to be completely avoided.

But here, exceptions have an advantage if we stop there: they provide an error description.

Fully-typed failures

Fixing that problem is pretty trivial with a strong type-system and algebraic data types. We want to use those to create a result type, that can either be something, or a typed error, that would contain exactly the same information you have in a regular exception.

C++ doesn’t really have that out of the box but it could be made, in the same way std::variant exists. Imagine a hypothetical std::either type and let’s implement a function that parses something:

std::either<Something, ParseError> parse(std::string const & input);

That function returns either a successful object (Something) or an error (ParseError).

With that signature, it’s clear that the function can fail with ParseError. The point is that the caller must do something about it. If they don’t know what to do with it — imagine a parser combinator or some code that doesn’t know how to handle a parse error and requires its caller to handle the error — then the function needs to abort and propagate the error upwards. That looks like a bit like the interface you have with exceptions… but here, the interface is visible at the type-level.

Obviously, you cannot use throw to propagate upwards. You need to use return from your function. With either a macro or some language construct, C++ could make that propagation smoother, but currently, it doesn’t have a proper way to do it. So we’d be left with macros only, or manual propagation. Since C++ doesn’t have pattern-matching nor exhaustive patterns, it would be pretty hard to implement that mechanism in a complete sound way. As with std::optional, it’s not perfect, but it would be slightly better than using opaque exceptions.

One final point. Sometimes, I wonder what it would be like to just give up on my ideas of using a strong type system in C++. The language is using exceptions and people are used to it. That’s the C++ way. So… why not changing the way exceptions work so that they’re not opaque, and propagate upwards? I remember the throw specifier, used to state what a function might throw. But again, it’s not enforced by compiler. Worse, it’s being deprecated in C++ 2020.

I voluntarily omitted any reference to either Haskell, Rust or any language like that so that people don’t think I’m trying to compare C++ to another language. I’m having a look on C++ after almost two decades using it and what else I’ve learned. The situation is, to me, frustrating. Because yes, whatever the good arguments against exceptions, people still use them and error handling in C++ is still about exceptions. So you still can have constructors that fail. You still depend a lot on documentation and your compiler cannot tell you when something is not okay. We are all fallible, way more than we think.

The stash is a temporary area working like a stack. You can push changes onto it via git stash or git stash save; you can pop changes from top with git stash pop. You can also apply a very specific part of the stack with git stash apply <stash id>. Finally you can get the list of all the stashes with git stash list.

We often use the git stash command to stash changes in order to make the working directory clear again so that we can apply a patch, pull some changes, change branch, and so on. For those purposes, the stash is pretty great.

However, I often forget about my stashes – I know I’m not the only one. Sometimes, I stash something and go to cook something or just go out, and when I’m back again, I might have forgotten about what I had stashed, especially if it was a very small change.

My current prompt for my shell, zsh, is in two parts. I set the PS1 environnment variable to set the regular prompt, and the RPROMPT environnment variable to set a reversed prompt, starting from the right of the terminal. My reversed prompt just performs a git command to check whether we’re actually in a git project, and get the current branch. Simple, but nice.

I came up to the realization that I could use the exact same idea to know whether I have stashed changes so that I never forget them! Here’s a screenshot to explain that:

As you can see, my prompt now shows me how many stashed changes there are around!

The code

I share the code I wrote with you. Feel free to use it, modify it and share it as well!

# …

function gitPrompt() {
  # git current branch
  currentBranch=`git rev-parse --abbrev-ref HEAD 2> /dev/null`
  if (($? == 0))
  then
    echo -n "%F{green}$currentBranch%f"
  fi

  # git stash
  stashNb=`git stash list 2> /dev/null | wc -l`
  if [ "$stashNb" != "0" ]
  then
    echo -n " %F{blue}($stashNb)%f"
  fi

  echo ''
}

PS1="%F{red}%n%F{cyan}@%F{magenta}%M %F{cyan}%~ %F{yellow}%% %f"
RPROMPT='$(gitPrompt)'

# …

Have fun!

Origin

luminance started as a Haskell package, extracted from a “3D engine” I had been working on for a while called quaazar. I came to the realization that I wasn’t using the Haskell garbage collector at all and that I could benefit from using a language without GC. Rust is a very famous language and well appreciated in the Haskell community, so I decided to jump in and learn Rust. I migrated luminance in a month or two. The mapping is described in this blog entry.

What is luminance for?

I’ve been writing 3D applications for a while and I always was frustrated by how OpenGL is badly designed. Let’s sum up the lack of design of OpenGL:

• weakly typed: OpenGL has types, but… it actually does not. GLint, GLuint or GLbitfield are all defined as aliases to primary and integral types (i.e. something like typedef float GLfloat). Try it with grep -Rn "typedef [a-zA-Z]* GLfloat" /usr/include/GL. This leads to the fact that framebuffers, textures, shader stages, shader program or even uniforms, etc. have the same type (GLuint, i.e. unsigned int). Thus, a function like glCompileShader expects a GLuint as argument, though you can pass a framebuffer, because it’s also represented as a GLuint – very bad for us. It’s better to consider that those are just untyped – :( – handles.
• runtime overhead: Because of the point above, functions cannot assume you’re passing a value of a the expected type – e.g. the example just above with glCompileShader and a framebuffer. That means OpenGL implementations have to check against all the values you’re passing as arguments to be sure they match the type. That’s basically several tests for each call of an OpenGL function. If the type doesn’t match, you’re screwed and see the next point.
• error handling: This is catastrophic. Because of the runtime overhead, almost all functions might set the error flag. You have to check the error flag with the glGetError function, adding a side-effect, preventing parallelism, etc.
• global state: OpenGL works on the concept of global mutation. You have a state, wrapped in a context, and each time you want to do something with the GPU, you have to change something in the context. Such a context is important; however, some mutations shouldn’t be required. For instance, when you want to change the value of an object or use a texture, OpenGL requires you to bind the object. If you forget to bind for the next object, the mutation will occurs on the first object. Side effects, side effects…

The goal of luminance is to fix most of those issues by providing a safe, stateless and elegant graphics framework. It should be as low-level as possible, but shouldn’t sacrifice runtime performances – CPU charge as well as memory bandwidth. That is why if you know how to program with OpenGL, you won’t feel lost when getting your feet wet with luminance.

Because of the many OpenGL versions and other technologies (among them, vulkan), luminance has an extra aim: abstract over the trending graphics API.

Types in luminance

In luminance, all graphics resources – and even concepts – have their own respective type. For instance, instead of GLuint for both shader programs and textures, luminance has Program and Texture. That ensures you don’t pass values with the wrong types.

Because of static warranties provided by compile-time, with such a scheme of strong-typing, the runtime shouldn’t have to check for type safety. Unfortunately, because luminance wraps over OpenGL in the luminance-gl backend, we can only add static warranties; we cannot remove the runtime overhead.

Error handling

luminance follows the Rust conventions and uses the famous Option and Result types to specify errors. You will never have to check against a global error flag, because this is just all wrong. Keep in mind, you have the try! macro in your Rust prelude; use it as often as possible!

Even though Rust needs to provide an exception handler – i.e. panics – there’s no such thing as exceptions in Rust. The try! macro is just syntactic sugar to:

match result {
  Ok(x) => x,
  Err(e) => return e
}

Stateless

luminance is stateless. That means you don’t have to bind an object to be able to use it. luminance takes care of that for you in a very simple way. To achieve this and keep performances running, it’s required to add a bit of high-level to the OpenGL API by leveraging how binds should happen.

Whatever the task you’re trying to reach, whatever computation or problem, it’s always better to gather / group the computation by batches. A good example of that is how magnetic hard drive disks work or your RAM. If you spread your data across the disk region (fragmented data) or across several non-contiguous addresses in your RAM, it will end up by unnecessary moves. The hard drive’s head will have to go all over the disk to gather the information, and it’s very likely you’ll destroy the RAM performance (and your CPU caches) if you don’t put the data in a contiguous area.

If you don’t group your OpenGL resources – for instances, you render 400 objects with shader A, 10 objects with shader B, then 20 objects with shader A, 32 objects with shader C, 349 objects with shader A and finally 439 objects with shader B, you’ll add more OpenGL calls to the equation – hence more global state mutations, and those are costly.

Instead of this:

1. 400 objects with shader A
2. 10 objects with shader B
3. 20 objects with shader A
4. 32 objects with shader C
5. 348 objects with shader A
6. 439 objects with shader B

luminance forces you to group your resources like this:

1. 400 + 20 + 348 objects with shader A
2. 10 + 439 objects with shader B
3. 32 objects with shader C

This is done via types called Pipeline, ShadingCommand and RenderCommand.

Pipelines

A Pipeline gathers shading commands under a Framebuffer. That means that all ShadingCommand embedded in the Pipeline will output to the embedded Framebuffer. Simple, yet powerful, because we can bind the framebuffer when executing the pipeline and don’t have to worry about framebuffer until the next execution of another Pipeline.

ShadingCommand

A ShadingCommand gathers render commands under a shader Program along with an update function. The update function is used to customize the Program by providing uniforms – i.e. Uniform. If you want to change a Programs Uniform once a frame – and only if the Program is only called once in the frame – it’s the right place to do it.

All RenderCommand embedded in the ShadingCommand will be rendered using the embedded shader Program. Like with the Pipeline, we don’t have to worry about binding: we just have to use the embedded shader program when executing the ShadingCommand, and we’ll bind another program the next time a ShadingCommand is ran!

RenderCommand

A RenderCommand gathers all the information required to render a Tessellation, that is:

• the blending equation, source and destination blending factors
• whether the depth test should be performed
• an update function to update the Program being in use – so that each object can have different properties used in the shader program
• a reference to the Tessellation to render
• the number of instances of the Tessellation to render
• the size of the rasterized points (if the Tessellation contains any)

What about shaders?

Shaders are written in… the backend’s expected format. For OpenGL, you’ll have to write GLSL. The backends automatically inserts the version pragma (#version 330 core for OpenGL 3.3 for instance). In the first place, I wanted to migrate cheddar, my Haskell shader EDSL. But… the sad part of the story is that Rust is – yet – unable to handle that kind of stuff correctly. I started to implement an EDSL for luminance with macros. Even though it was usable, the error handling is seriously terrible – macros shouldn’t be used for such an important purpose. Then some rustaceans pointed out I could implement a (rustc) compiler plugin. That enables the use of new constructs directly into Rust by extending its syntax. This is great.

However, with the hindsight, I will not do that. For a very simple reason. luminance is, currently, simple, stateless and most of all: it works! I released a PC demo in Köln, Germany using luminance and a demoscene graphics framework I’m working on:

pouët.net link

youtube capture

ion demoscene framework

While developping Céleri Rémoulade, I decided to bake the shaders directly into Rust – to get used to what I had wanted to build, i.e., a shader EDSL. So there’re a bunch of constant &'static str everywhere. Each time I wanted to make a fix to a shader, I had to leave the application, make the change, recompile, rerun… I’m not sure it’s a good thing. Interactive programming is a very good thing we can enjoy – yes, even in strongly typed languages ;).

I saw that gfx doesn’t have its own shader EDSL either and requires you to provide several shader implementations (one per backend). I don’t know; I think it’s not that bad if you only target a single backend (i.e. OpenGL 3.3 or Vulkan). Transpiling shaders is a thing, I’ve been told…

sneaking out…

Feel free to dig in the code of Céleri Rémoulade here. It’s demoscene code, so it had been rushed on before the release – read: it’s not as clean as I wanted it to be.

I’ll provide you with more information in the next weeks, but I prefer spending my spare time writing code than explaining what I’m gonna do – and missing the time to actually do it. ;)

Keep the vibe!

Nowadays, there is a cool concept out there in the Functional Programming world which is called FRP. It stands for Functional Reactive Programming and is a pretty decent way to make event-driven programs.

The problem with FRP is that, beside Wikipedia, Haskell.org and a few other resources, like Conal Elliott’s papers, we lack learning materials. Getting into FRP is really not trivial and because of the lack of help, you’ll need to be brave to get your feet wet.

Because I found it hard learning it from scratch and because I think it’s a good thing to pass knowledge by, I decided to write a few about it so that people can learn via an easier path.

I’ll be talking about netwire, which is not the de-facto library to use in Haskell, because, eh… we don’t have any. However, netwire exposes a lot of very interesting concepts and helped me to understand more general abstractions. I hope it’ll help you as well. :)

The FRP Thing

Event-driven programming context

In traditional event-driven programming codebase, you’d find constructions such as events polling (when you explicitely retrieve last occurring events), callbacks and event handlers. GLFW is a very famous example of callback uses for event-driven programming. Such functions as glfwSetWindowCloseCallback require you to pass a callback that will be called when the event occurs. While that way to go seems nice, it’s actually error-prone and ill-formed design:

• you eventually end up with spaghetti code
• debugging callbacks is a true nightmare as the codebase grows
• because of the first point, the code doesn’t compose – or in very minimal ways – and is almost impossible to test against
• you introduce side-effects that might introduce nasty bugs difficult to figure out
• debugging is like hitting your head on a tree log

However, it’s not black or white. Callbacks are mandatory. They’re useful, and we’ll see that later on.

What FRP truely is?

FRP is a new way to look at event-driven programming. Instead of representing reaction through callbacks, we consume events over time. Instead of building a callback that will be passed as reaction to the setPushButtonCallback function, we consume and transform events over time. The main idea of FRP could be summed up with the following concepts:

• behaviors: a behavior is a value that reacts to time
• events: events are just values that have occurrences in time
• switching: the act of changing of behavior

Behaviors

According to Wikipedia, a behavior is the range of actions and mannerisms made by individuals, organisms, systems, or artificial entities in conjunction with themselves or their environment, which includes the other systems or organisms around as well as the (inanimate) physical environment. If we try to apply that to a simple version of FRP that only takes into account the time as external stimulus, a behavior isany kind of value that consumes time. What’s that? Well…

newtype Behavior a = Behavior { stepBehavior :: Double -> a }

A behavior is a simple function from time (Double) to a given value. Let’s take an example. Imagine you want to represent a cube rotating around the X axis. You can represent the actual rotation with a Behavior Rotation, because the angle of rotation is linked to the time:

rotationAngle :: Behavior Rotation
rotationAngle = Behavior $ \t -> rotate xAxis t

Pretty simple, see?! However, it’d would more convenient if we could chose the type of time. We don’t really know what the time will be in the final application. It could be the current UTC time, it could be an integral time (think of a stepped discrete simulation), it could be the monotonic time, the system time, something that we don’t even know. So let’s make our Behavior type more robust:

newtype Behavior t a = Behavior { stepBehavior :: t -> a }

Simple change, but nice improvement.

That is the typical way to picture a behavior. However, we’ll see later that the implementation is way different that such a naive one. Keep on reading.

Events

An event is something happening at some time. Applied to FRP, an event is a pair of time – giving the time of occurrence – and a carried value:

newtype Event t a = Event { getEvent :: (t,a) }

For instance, we could create an event that yields a rotation of 90° around X at 35 seconds:

rotate90XAt35s :: Event Float Rotation
rotate90XAt35s = Event (35,rotate xAxis $ 90 * pi / 180)

Once again, that’s the naive way to look at events. Keep in mind that events have time occurrences and carry values.

Behavior switch

You switch your behavior every time. Currently, you’re reading this paper, but you may go grab some food, go to bed, go to school or whatever you like afterwards. You’re already used to behavior switching because that’s what we do every day in a lifetime.

However, applying that to FRP is another thing. The idea is to express this:

“Given a first behavior, I’ll switch to another behavior when a given event occurs.”

This is how we express that in FRP:

switch :: Behavior t a -> Event t (Behavior t a) -> Behavior t a

Let me decrypt switch for you.

The first parameter, a Behavior t a, is the initial behavior. For instance, currently, you’re reading. That could be the first behavior you’d pass to switch.

The second parameter, an Event t (Behavior t a), is an event that yields a new Behavior t a. Do you start to get it? No? Well then:

switch reading finished

reading is the initial behavior, and finished is an event that occurs when you’re done reading. switch reading finished is then a behavior that equals to reading until finished happens. When it does, switch reading finished extracts the behavior from the event, and uses it instead.

I tend to think switch is a bad name, and I like naming it until:

reading `until` finished

Nicer isn’t it?! :)

Stepping

Stepping is the act of passing the input – i.e. the time t in our case – down to the Behavior t a and extract the resulting a value. Behaviors are commonly connected to each other and form a reactive network.

That operation is also often refered to as reactimation in certain implementations, but is more complex than just stepping the world. You don’t have to focus on that yet, just keep in mind the reactimate function. You might come across it at some time.

Before going on…

Everything you read in that paper until now was just pop-science so that you understand the main idea of what FRP is. The next part will cover a more decent and real-world implementation and use of FRP, especially efficient implementations.

Let’s build a FRP library!

The first common error a lot of programmers make is trying to write algorithms or libraries to solve a problem they don’t even know. Let’s then start with an example so that we can figure out the problem.

Initial program

Setting up

Let’s say we want to be able to control a camera with a keyboard:

• W would go forward
• S would go backward
• A would left strafe
• D would right strafe
• R would go up
• F would go down

Let’s write the Input type:

data Input
  = W
  | S
  | A
  | D
  | R
  | F
  | Quit
    deriving (Eq,Read,Show)

Straight-forward. We also have a function that polls events from IO:

pollEvents :: IO [Input]
pollEvents = fmap treatLine getLine
  where
    treatLine = concatMap (map fst . reads) . words

We use [Input] because we could have several events at the same time (imagine two pressed keys). The function is using dumb implementation in order to abstract over event polling. In your program, you won’t use getLine but a function from SDL or similar.

And the camera:

newtype Camera = Camera { _cameraPosition :: V3 Float } deriving (Eq,Read,Show)

makeLenses ''Camera

V3 is a type from linear. You’ll need that lib then, and import Linear.V3 to make the Camera compile. You’ll also need lens and the GHC TemplateHaskell extension enabled as well as import Control.Lens.

Ok, let’s react to events!

First attempt: the regular and naive one

The idea is to use some kind of state we’ll change on an event. In our case the state is pretty simple:

data AppSt = AppSt {
    _appCamera :: Camera
  } deriving (Eq,Read,Show)
  
makeLenses ''AppSt

updateAppSt :: AppSt -> Input -> Maybe AppSt
updateAppSt appst input = case input of
  W -> Just $ appst & appCamera . cameraPosition . _z -~ 0.1
  S -> Just $ appst & appCamera . cameraPosition . _z +~ 0.1
  A -> Just $ appst & appCamera . cameraPosition . _x -~ 0.1
  D -> Just $ appst & appCamera . cameraPosition . _x +~ 0.1
  F -> Just $ appst & appCamera . cameraPosition . _y -~ 0.1
  R -> Just $ appst & appCamera . cameraPosition . _y +~ 0.1
  Quit -> Nothing

A lot of boilerplate on updateAppSt, but that doesn’t matter that much. The idea is to modify the application state and just return it for all inputs but Quit, in which case we return Nothing to express the wish to quit the application.

I’ve been using that idea for a while. It’s simple, nice and neat, because we don’t spread IO actions in our program logic, which remains then pure. That’s a very good way of doing it, and in most cases, it’ll even be sufficient. However, that idea suffers from a serious issue: it doesn’t scale.

Who has only one camera? No one. You have a camera – maybe more than just one, lights, objects, terrains, AI, sounds, assets, maps and so on and so forth. Our little AppSt type would explode as we add objects. That doesn’t scale at all. You could, though, go on and add all your objects in your AppSt – I did that once, it was a pretty harsh experience.

Furthermore, imagine you want to add a new behavior to the camera, like being able to handle the mouse cursor move – Input being augmented, of course. You’d need to change / add lines in our updateAppSt function. Imagine how messy updateAppSt would be… That would, basically, gather all reactions into a single function. Not neat.

Adding FRP

FRP enables us to use our reactive values as if they are regular values. You can add reactive values, you can substract them, combine them in any way you want. The semantics of your values should be true for the reactive values.

Typically, with FRP, you don’t have event handlers anymore. The codebase can then grow sanely without having to accumulate big states every now and then. FRP applications scale and compose pretty well.

Let’s start with a simple FRP implementation for our example.

Naive FRP implementation

Let’s start with the behavior:

newtype Behavior t a = Behavior { stepBehavior :: t -> a }

How could we implement our camera’s behavior with that? We actually can’t since we don’t have any ways to pass events.

“I guess we could build a Behavior t Camera by passing our Input to the initial function?”

Something like this?

camera inputs = Behavior $ \_ -> -- implement the behavior with inputs

That could be a way to go, yeah. However, how would you implement switching with that? Remember the type of until:

until :: Behavior t a -> Event (Behavior t a) -> Behavior t a

camera is not a behavior, it’s a function from events to a behavior. You have to apply the events on camera in order to get its behavior. Once you’ve done that, you cannot pass events to the next behavior. What a pity. That is more a configured behavior than a behavior consuming inputs / events.

With the current Behavior t a implementation, a behavior network is reduced to a function t -> a, basically. Then, the only stimulus you got from outside is… time. We lack something.

Arrowized behaviors

“A way to forward events?”

Yes! But more mainly, a way to extend our Behavior t a with inputs! Don’t get me wrong, we are not talking about a reactive value here. We are talking about a reactive relationship:

newtype Behavior t a b = Behavior { stepBehavior :: t -> a -> b }

That’s way better! Our new behavior represents a relationship between two reactive objects. The b is our old a, and the new a is the input! Let’s see what we can do with that.

camera :: Behavior t [Input] Camera
camera = Behavior (const treatEvents)
  where
    treatEvents events
      | W `elem` events = Camera $ V3 0 0 (-0.1)
      | S `elem` events = Camera $ V3 0 0 0.1
      | otherwise = Camera $ V3 0 0 0

That is not exactly what we intented to express. Here, if we push the W button, we just put the camera in V3 0 0 (-0.1), while we’d like to move it forward. That is due to the fact we need switching.

The idea is the following: the initial behavior is idleing. We just don’t do anything. Then, we switch to a given behavior when a given event occurs. We’ll need recursion so that we can ping-pong between behaviors. Let’s write the idleing behavior:

idleing :: Behavior t ([Input],Camera) Camera
idleing = Behavior (const snd)

That behavior requires as input our Input events list and a Camera and simply returns the Camera. Pretty nice.

How do we switch then? We need Event. Consider this:

newtype Event t a = Event { getEvent :: (t,a) }

In order to switch, we need a to be a behavior. In the first place, we’ll create several Event t [Input] and pass them as input to the behavior network. How could we change the [Input] to something more interesting? Simple: Functor!

instance Functor (Event t) where
  fmap f (Event e) = Event (fmap f e)

Note: because of Event t a being a newtype, you should rather use the GHC GeneralizedNewtypeDeriving extension to automatically let GHC infer the instance for you.

newtype Event t a = Event { getEvent :: (t,a) } deriving (Functor)

Then, we can use the Functor instance to change the type of the carried value of the event. That’s great because we don’t change the occurrence time, only the carried value. Transforming events is really important in FRP. We can then transform the [Input] into a single behavior:

inputToBehavior i = case i of
  W -> Behavior $ \_ (_,cam) -> cam & cameraPosition . _z -~ 0.1
  S -> Behavior $ \_ (_,cam) -> cam & cameraPosition . _z +~ 0.1
  A -> -- and so on
  D -> -- and so forth
  F -> -- ;)
  R -> -- ...
  _ -> Behavior $ \_ (_,cam) -> cam

Pretty simple, see? When we push W, we go forward forever. We could have implemented the function above with another until call in order to go back to idleing, making some kind of behavior loop.

However, switching is fairly poorly implemented here. It’s not very efficient, and requires a ton of boilerplate.

Auto

There is a very cool type out there called Auto, used to implement automatons.

newtype Auto a b = Auto { runAuto :: a -> (b,Auto a b) }

An Auto a b is a function-like structure. It has an input and an output. The difference with a regular function is the fact it also has a secondary output, which is another Auto a b. That is, it’s the next automaton to be used.

Auto a b wraps pretty cool concepts, such as locally defined states. It’s also a great ally when implementing switching in a FRP system, because we can easily state that Behavior ≃ Auto. A Behavior is a function from the environment state to the next reactive value, and has also another output representing what to do “next”.

Let’s then change our Behavior type to make it look like a bit more like Auto:

newtype Behavior t a b = Behavior { stepBehavior :: t -> a -> (b,Behavior t a b) }

Yeah, that’s it! That’s a pretty good start!

Useful abstractions

Before going on, I’d like to introduce those scary abstractions you are afraid of. Because they’re actually not. They’re all simple. At least for Haskell purposes.

Note: I do know we could simply use the GeneralizedNewtypeDeriving` extension but I want to detail all the implementation, so we’ll see how to implement all the nice abstractions.

Arrow

Arrows are a generalization of functions along the axis of computation. A computation has inputs and outputs. So does a behavior.

Although arrows are not really used in Haskell, they’re ultra simple (themselves and the common combinators built over the abstraction) and useful in some cases.

In order to implement arrows, we need to provide code for both the arr function, which type is arr :: (Arrow a) => (b -> c) -> a b c and first, which type is first :: (Arrow a) => a b c -> a (b,d) (c,d). arr is used to lift a common function into the arrowized version, and first takes an arrow which takes a value as input and exposes an arrow that takes a pair as input, applying the given function on the first value of the pair. Let’s implement that:

instance Arrow (Behavior t) where
  arr f = fix $ \r -> Behavior $ \t a -> (f a,r)
  first f = Behavior $ \t (b,d) ->
    let (c,fn) = stepBehavior f t b
    in ((c,d),first fn)

Category

A category basically exposes two concepts: composition and identity. In our case, the identity represents a constant behavior in time and the composition composes two behaviors in time. Let’s implement Category by providing implementation for both id and (.):

instance Category (Behavior t) where
  id = arr id
  x . y = Behavior $ \t a ->
    let (yr,yn) = stepBehavior y t a
        (xr,xn) = stepBehavior x t yr
    in (xr,xn . yn)

Note: because of Prelude exporting specialized implementation of id and (.) – the function ones – you should hide them in order to implement Category:

import Prelude hiding ( (.), id )

Semigroup

A semigroup is a pretty cool algebraic structure used in Haskell to represent “anything that associates”. It exposes an associative binary function over a set. In the case of behaviors, if two behaviors output semigroup values, we can associates the behaviors to build a single one.

A Semigroup is implemented via a single typeclass method, (<>). Let’s do that for behaviors:

instance (Semigroup b) => Semigroup (Behavior t a b) where
  x <> y = Behavior $ \t a ->
    let (xr,xn) = stepBehavior x t a
        (yr,yn) = stepBehavior y t a
    in (xr <> yr,xn <> yn)

Simple and neat.

Functor

You might already know that one since I talked about it a few lines ago, but let’s write the instance for our Behavior:

instance Functor (Behavior t a) where
  fmap f b = Behavior $ \t a ->
    let (br,bn) = stepBehavior b t a
    in (f br,fmap f bn)

Pretty cool eh?

Applicative

A very known one too. Let’s see how we could implement Applicative:

instance Applicative (Behavior t a) where
  pure = arr . const
  f <*> x = Behavior $ \t a ->
    let (fr,fn) = stepBehavior f t a
        (xr,xn) = stepBehavior x t a
    in (fr xr,fn <*> xn)

Profunctor

This one is special. You don’t have to know what a profunctor is, but eh, you should, because profunctors are pretty simple to use in Haskell, and are very useful. I won’t explain what they are – you should have a look at this article for further details.

If you do know them, here’s the implementation for dimap:

instance Profunctor (Behavior t) where
  dimap l r x = Behavior $ \t a ->
    let (xr,xn) = stepBehavior x t (l a)
    in (r xr,dimap l r xn)

Inhibition

Bare concept

Behaviors consume environment state and have outputs. However, they sometimes just don’t. They don’t output anything. That could be the case for a behavior that only emits during a certain period of time. It could also be the case for a signal function that’s defined on a given interval: what should we output for values that lie outside?

Such a scenario is called inhibition. There’re several solutions to implement inhibition. The simplest and most famous one is by using Maybe as a wrapper over the output. Like the following:

Behavior t a (Maybe b)

If (Maybe b) is Nothing, the output is undefined, then the behavior inhibits.

However, using a bare Maybe exposes the user directly to inhibition. There’s another way to do that:

newtype Behavior t a b = Behavior { stepBehavior :: t -> a -> Maybe (b,Behavior t a b) }

Here we are. We have behaviors that can inhibit. If a behavior doesn’t inhibit, it returns Just (output,nextBehavior), otherwise it outputs Nothing and inhibits forever.

Exercise: try to reimplement all the above abstractions with the new type of Behavior.

We can add a bunch of other interesting functions:

Inhibition-related combinators

dead :: Behavior t a b
dead = Behavior $ \_ _ -> Nothing

one :: b -> Behavior t a b
one x = Behavior $ \_ _ -> Just (x,dead)

dead is a behavior that inhibits forever. That is, it doesn’t produce any value at any time.

one x produces x once, and then inhibits forever. That’s a nice combinator to use when you want to pulse values in time. We’ll see later that it’s very useful to represent discrete events, like key presses or mouse motion.

However, inhibiting can be useful. For instance, we can implement a new kind of behavior switching using inhibition. Let’s try to implement a function that takes two behaviors and switches to the latter when the former starts inhibiting:

revive :: Behavior t a b -> Behavior t a b -> Behavior t a b
revive x y = Behavior $ \t a -> case stepBehavior x t a of
  Just (xr,xn) -> return (xr,revive xn y)
  Nothing -> stepBehavior y t a

(~>) :: Behavior t a b -> Behavior t a b -> Behavior t a b
(~>) = revive

(~>) is a handy alias to revive. Then, a ~> b is a behavior that is a until it inhibits, afterwhile it’s b. Simple, and useful.

In netwire, revive – or (~>) – is (-->). There’s also an operator that does the opposite thing: (>--). a >-- b is a until b starts producing – i.e. until b doesn’t inhibit anymore.

Exercise: write the implementatof of (>~), our version for netwire’s (>--).

Behaviors revisited

Now you have a better idea of how you could implement a behavior, let’s talk about netwire’s one.

netwire’s behavior type is called Wire. It’s actually:

Wire s e m a b

s is the session time – it’s basically a type that’s used to extract time. e is the inhibition value. m is a inner monad – yes, you can use monadic code within netwire, which is not really useful actually, except for Reader, I guess. And a and b are respectively inputs and outputs.

“What is that inhibition type?”

Yeah, netwire doesn’t use Maybe for inhibition. Picture Wire as:

newtype Wire s e m a b = Wire { stepWire :: s -> a -> m (Either e (b,Wire s e m a b)) }

Instead of using Maybe (b,Wire s e m a b), it uses Either. Some functions require e to be a Monoid. I guess netwire uses that to accumulate during inhibition. I don’t see decent use cases of such a feature, but it’s there. I tend to use this kind of wire in all my uses of netwire:

Wire s () Identity a b -- I think this is the most common type of wire

Keep in mind that although you can set m to IO, it’s not what netwire – and FRP – was designed for.

Events

What about events? Well, netwire exposes events as a home-made Maybe:

data Event a
  = Event a
  | NoEvent
    deriving (Eq,Show)

instance Functor Event where
  fmap f e = case e of
    Event a -> Event (f a)
    NoEvent -> NoEvent

That’s actually enough, because we can attach Event a to time occurences with Behavior t b a. You’ll find every now and then functions using Wire s e m (Event a) b, for instance. You should get used to that as you write toy examples, and real-world ones, of course.

In the end

What a trek… As you can see, we were able to approach netwire’s implementation understanding pretty closely. There are a few concepts I haven’t covered – like intrinsic switches, continuable switches, deferred switches… – but I don’t pretend having a comprehensive FRP article. You’ll have to dig in a bit more ;)

I’ll write another article about FRP and netwire to implement the camera example with netwire so that you can have a concrete example.

So, what’s new?

OpenGL allows programmers to send vertices to the GPU through what is called a vertex array. Vertex specification is performed through several functions, operating on several objects. You need, for instance, a vertex buffer object, an index buffer object and a vertex array object. The vertex buffer stores the vertices data.

For instance, you could imagine a teapot as a set of vertices. Those vertices have several attributes. We could use, for instance, a position, a normal and a bone index. The vertex buffer would be responsible of storing those positions, normals and bone indices. There’re two ways to store them:

1. interleaved arrays ;
2. deinterleaved arrays.

I’ll explain those later on. The index buffer stores integral numbers – mainly set to unsigned int – that index the vertices, so that we can connect them and create lines, triangles or more complex shapes.

Finally, the vertex array object is a state object that stores links to the two buffers and makes a connection between pointers in the buffer and attribute indices. Once everything is set up, we might only use the vertex array object. The exception is when we need to change the geometry of an object. We need to access the vertex buffer and the index buffer and upload new data. However, for now, that feature is disabled so that the buffers are not exposed to the programmer. If people think that feature should be implemented, I’ll create specialized code for that very purpose.

Interleaved and deinterleaved arrays

Interleaved arrays might be the most simple to picture, because you use such arrays every day when programming. Let’s imagine you have the following type in Haskell:

data Vertex = Vertex {
    vertPos    :: X
  , vertNor    :: Y
  , vertBoneID :: Z
  } deriving (Eq,Show)

Now, the teapot would have several vertices. Approximately, let’s state the teapot has five vertices – yeah, ugly teapot. We can represent such vertices in an interleaved array by simply recording them in a list or an array:

As you can see, the attributes are interleaved in memory, and the whole pattern is cycling. That’s the common way to represent an array of struct in a lot of languages, and it’s very natural for a machine to do things like that.

The deinterleaved version is:

As you can see, with deinterleaved arrays, all attributes are extracted and grouped. If you want to access the third vertex, you need to read the third X, the third Y and the third Z.

Both the methods have advantages and drawbacks. The cool thing about deinterleaved arrays is that we can copy huge regions of typed memory at once whilst we cannot with interleaved arrays. However, interleaved arrays store continuous structures, so writing and reading a structure back might be faster.

An important point to keep in mind: because we plan to pass those arrays to OpenGL, there’s no alignment restriction on the structure. That is, everything is packed, and we’ll have to pass extra information to OpenGL to tell it how to advance in memory to correctly build vertices back.

Generalized tuple

I think I haven’t told you yet. I have a cool type in luminance: the (:.) type. No, you don’t have to know how to pronounce that. I like to call it the gtuple type, because it’s a generalized tuple. You can encode (a,b), (a,b,c) and all kind of tuples with (:.). You can even encode single-typed infinite tuple! – a very special kind of list, indeed.

data a :. b = a :. b

infixr 6 :.

-- a :. b is isomorphic to (a,b)
-- a :. b :. c is isomorphic to (a,b,c)

newtype Fix f = Fix (f (Fix f)) -- from Control.Monad.Fix
type Inf a = Fix ((:.) a) -- infinite tuple!

Pretty simple, but way more powerful than the regular, monomorphic tuples. As you can see, (:.) is a right-associative. That means that a :. b :. c = a :. (b :. c).

That type will be heavily used in luminance, thus you should get your fet wet with it. There’s actually nothing much to know about it. It’s a Functor. I might add other features to it later on.

The Storable trick

The cool thing about (:.) is that we can provide a Storable instance for packed memory, as OpenGL requires it. Currently, the Storable instance is implemented like this:

instance (Storable a,Storable b) => Storable (a :. b) where
  sizeOf (a :. b) = sizeOf a + sizeOf b
  alignment _ = 1 -- packed data
  peek p = do
    a <- peek $ castPtr p
    b <- peek . castPtr $ p `plusPtr` sizeOf (undefined :: a)
    pure $ a :. b
  poke p (a :. b) = do
    poke (castPtr p) a
    poke (castPtr $ p `plusPtr` sizeOf (undefined :: a)) b

As you can see, the alignment is set to 1 to express the fact the memory is packed. The peek and poke functions use the size of the head of the tuple to advance the pointer so that we effectively write the whole tuple in packed memory.

Then, let’s rewrite our Vertex type in terms of (:.) to see how it’s going on:

type Vertex = X :. Y :. Z

If X, Y and Z are in Storable, we can directly poke one of our Vertex into a luminance buffer! That is, directly into the GPU buffer!

Keep in mind that the Storable instance implements packed-memory uploads and reads, and won’t work with special kinds of buffers, like shader storage ones, which require specific memory alignment. To cover them, I’ll create specific typeclasses instances. No worries.

Creating a vertex array

Creating a vertex array is done through the function createVertexArray. I might change the name of that object – it’s ugly, right? Maybe Shape, or something cooler!

createVertexArray :: (Foldable f,MonadIO m,MonadResource m,Storable v,Traversable t,Vertex v)
                  => t v
                  -> f Word32
                  -> m VertexArray

As you can see, the type signature is highly polymorphic. t and f represent foldable structures storing the vertices and the indices. And that’s all. Nothing else to feed the function with! As you can see, there’s a typeclass constraint on v, the inner vertex type, Vertex. That constraint ensures the vertex type is representable on the OpenGL side and has a known vertex format.

Disclaimer: the Traversable constraint might be relaxed to be Foldable very soon.

Once tested, I’ll move all that code from the unstable branch to the master branch so that you guys can test it. :)

About OpenGL…

I eventually came to the realization that I needed to inform you about the OpenGL prerequisites. Because I want the framework to be as modern and well-designed as possible, you’ll need… OpenGL 4.5. The latest version, indeed. You might also need an extension, ARB_bindless_texture. That would enable the framework to pass textures to shader in a very stateless way, which is our objective!

I’ll let you know what I decide about that. I don’t want to use an extension that is not implemented almost everywhere.

What’s next?

Well, tests! I need to be sure everything is correctly done on the GPU side, especially the vertex format specification. I’m pretty confident though.

Once the vertex arrays are tested, I’ll start defining a render interface as stateless as I can. As always, I’ll keep you informed!

Before starting up, if you don’t know what hop.nvim is, here’s a small excerpt from the README:

Hop is an EasyMotion-like plugin allowing you to jump anywhere in a document with as few keystrokes as possible. It does so by annotating text in your buffer with hints, short string sequences for which each character represents a key to type to jump to the annotated text. Most of the time, those sequences’ lengths will be between 1 to 3 characters, making every jump target in your document reachable in a few keystrokes.

Today, I want to talk about something at the core of the design of Hop: permutations, and a new algorithm I implemented to (greatly) optimize permutations in Hop.

Disclaimer: it might be possible that the algorithm described here has an official name, as I’m using a well-known data structure, traversing in a way that is also well established. Even though I came up with it, I don’t really know whether it has a name so if you recognize it, or think it is similar to something, feel free to tell me!

Permutations

When you run a Hop command (whether as a Vim command, such as :HopWord, or from Lua, like :lua require'hop'.hint_words()), Hop is going to place labels, called hints, in your window, over your buffer, describing sequences of keys to type to jump to the annotated location in the buffer. Those key sequences are generated as permutations of your input key set, of different lengths. Your input key set is basically the set of keys you expect to type to hop around. For instance, the default key set is made for QWERTY and is:

asdghklqwertyuiopzxcvbnmfj

The way Hop works is taking those keys and generating permutations of increasing length. The goal is to obviously type as less as possible (remember: Neovim motion on speed!), so we want to generate 1-sequence permutations first, such as a, s, d, etc., then switch to 2-sequence permutations, e.g. aj, kn, etc. The most important part of the work done by Hop is to generate those permutations in a smart way.

Until today, I had implemented a single algorithm doing this. Let’s describe it so that I can introduce the actual topic of this article.

First permutation generation algorithm

The first algorithm used to generate permutations in Hop was designed around the idea of being able to generate permutations in a co-recursive way (even though it’s not using co-recursion in Lua): given a permutation, you can generate the next one by running the algorithm on the permutation. Doing that over and over generates more permutations. You can sum it up like this:

let first_perm = next_perm({})
let second_perm = next_perm(first_perm)
let third_perm = next_perm(second_perm)
-- etc. etc. stop at a given condition and return all the permutations

In functional programming languages, we call that kind of co-recursion an unfold. We stop building / generating when meeting a condition. In our case, the condition is when we reach the number of permutations to generate. This first algorithm had several constraints I wanted satisfied:

1. It has to be fast and co-recursive, so that we can pass it the number of permutations to generate and simply generate them until we have reached the number of desired permutations.
2. It has to take into account the user input key set.
3. It has to generate permutations minimizing the number of keys required to jump.
4. Because permutations will be distributed based on the Manhattan distance to the cursor, they must be ordered / sorted in a way that the first permutations in the list are the shorter ones and the last ones are the longer ones.

We already saw 1., so let’s talk about the three remaining points. Taking into account the key set of the user, with this algorithm, is done by splitting it into two sub-sets:

• A set called terminal key set, containing terminal keys. Those keys are used only in terminal position in sequences — i.e. at the very right-most position in the sequence. For instance, in the sequence abcde, e is a terminal key.
• A set called sequence key set, containing sequence keys. Those are keys found as prefixes of terminal keys in sequences. For instance, in the sequence abcde, a, b, c and d all appear before e, so they are sequence keys.

How to know which key is terminal and which is sequence? Well, I use a simple parameter for that, that can be modified in the user configuration of Hop: term_seq_bias (:help hop-config-term_seq_bias if you are interested). It is a floating number parameter specifying the ratio of terminal vs. sequence keys to use. Imagine you have 100 keys in your key set (you typically will have between 20 and 30), setting this parameter to 3 / 4 makes it use 75 terminal keys and 25 sequence keys.

Then, given those two sets, we start from the 0-sequence permutation, a.k.a. {}, and we start using terminal keys. If we have abc as terminal keys and de as sequence keys, we will get the permutations 'a', 'b' and 'c' for n = 3. If we ask permutations for n = 4, we will get 'a', 'b', 'c' but not 'd', as it’s a sequence key. Instead, we will start a new layer by incrementing the dimension of sequences, yielding 2-sequence permutations: we will then generate 'da'. For n = 6, the last permutation in the list is 'dc', which means that for n = 7, we have to do something, as we have run out of terminal keys. Instead of starting a new layer (3-sequence permutations), we traverse the permutation in reverse order, checking that we have exhausted all the sequence keys. Here, we can see that 'd' is not the last sequence key, so we can use the next one, e, and start a new sequence at ea, then eb, ec… and guess what permutation is the next? Since we have run out of both terminal keys and sequence keys, we need to use 3-sequence keys: the next permutation will be dda.

This algorithm is interesting because it allows people to bias (hence the name) the distribution of terminal and sequence keys. However, it is pretty obvious that this algorithm does a pretty poor job at minimizing the overall number of keys to type: it will minimize the number of keys to type for short hops, mostly around the cursor and at mid-distance. I highly advise to use either 3 / 4 or even 0.5 for the bias value. Other values yield… weird results.

The problem and finding a solution

Very quickly, I have noticed something a bit annoying with Hop. Even though it is pretty fast, the distribution of keys for long jumps is often using 3-sequence permutations. And where does it make sense to use Hop the most? For mid to long range jumps. Vim and Neovim are already pretty good at short jumps. For instance, jumping to characters on the same line can be achieved with f and F. If you want to jump to a word on the line above, you can just press k and use horizontal jumps.

I don’t necessarily agree that those are always ideal (and, well, I do use Hop for short hops too), but the situation is not ideal for long jumps in Vim / Neovim. See, I’ve been using Vim and Neovim for more than 12 years now, and I’ve seen lots of people using it. Most of the time, what people use for long jumps is either (or a combination of) one of these:

• Turn on relativenumber and look at relative numbers to jump to the line where the location appears in, press something like 17k or 17j, then use the f / F motions.
• Use the real line number and commands such as :153 or 153gg to jump to line 153, and do the same as the previous point.
• Use { / { / % to quickly skip large portions of text and arrive at destination in less typing effort (I’m actually a big user of %).
• Use marks, LSP, tags etc. to directly jump to semantic locations.

Among all those options, even when you combine them, you will always have to type more keys / take more time to do long jumps. For instance, considering we can jump with f to our location l because it is unique on the line we want to go to, assuming it’s on line 1064, 45 lines above our cursor:

• With relativenumber, we have to press 45kfl: between 5 and 6 keys (depending on whether you have to press shift on your keyboard layout for the digits).
• With real line number, 1064ggfl, between 8 and 9 keys.

So clearly, Hop should help for those jumps as much as possible, and the previous algorithm, even though already an enhancement over typing relative numbers or real line numbers, can still be enhanced. It is already pretty good because it will provide you with, most of the time, between 1-sequence and 3-sequence permutations. For long jumps, assume the longest: 3 keys, plus one key to trigger the Hop mode, you get 4 keys to type at most to jump anywhere.

The goal is to reduce that to 2 keys, i.e. 2-sequence at most, most of the time — 3 keys if you count the key to start Hop. In order to understand the concept of this new algorithm, let’s focus on what was wrong with the former. Consider the following, using abc as terminal keys and de as sequence keys:

-- n = 3
a b c

-- n = 4
--  last 1-sequence
--  v
a b c da

-- n = 6
a b c da db dc

-- n = 9
a b c da db dc ea eb ec

-- n = 10
--                   last 2-sequence
--                   v
a b c da db dc ea eb ec dda

You can see that after only 9 words, we are already using 3-sequence permutations. What about, for instance, the following sequences:

aa ab ac bb dd de …

Obviously, because of the rules explained above about the difference between terminal and sequence keys, those are forbidden: indeed, they would yield ambiguous sequences. For instance, aa and a both start with the same key and one is terminal at a given depth (1-sequence) while the other still has one level (2-sequence): what should we do? Trigger the 1-sequence and never be able to jump to the 2-sequence? Use a timeout so that we have the time to type the second a? But that would make jumping to terminal keys feel delayed / slow, so that’s a hard no. What’s the problem?

The problem is that we are not efficiently using the key space by forbidding those sequences. If you pay attention, you should actually be able to use all possible 2-sequence permutations. But in order to do that… we have to forbid using 1-sequence permutations! Forbidding that will make all 2-sequence permutations unique and unambiguous. The difference is massive: instead of having only 9 permutations shorter than 3-sequence ones, we know have 25, which is the number of keys in the user key set squared: 'abcde' is 5 keys, and 5² is 25. For the default key set for QWERTY, which has 26 keys, it means 26² = 676 maximum 2-sequence permutations, which is a comfortable number for the visible part of your buffer.

The new algorithm: tries and backtrack filling

The new algorithm’s idea relies on using all the keys from your input key set. It doesn’t split it into terminal and sequence keys. It creates tries (a type of search tree, optimized for packed storage and fast traversal) to store the permutations and backtracks to remove ambiguity as we ask for more permutations. For instance, using the user input key set 'abcde':

-- n = 5
a b c d e

-- n = 6
--      e was transformed to ea
--      v
        a b
a b c d e e

-- n = 7
        a b c
a b c d e e e

-- n = 9
        a b c d e
a b c d e e e e e

As you can see, for n = 6, instead of adding a new layer, the algorithm backtracks to fill what is possible to fill: in our case, e, by replacing it with ea and inserting the new permutation at eb. Once a given layer is saturated, the algoritm backtracks again, trying to saturate another layer:

-- n = 10
--    d was transformed to da
--    v
      a b a b c d e
a b c d d e e e e e

-- n = 13
      a b c d e a b c d e
a b c d d d d d e e e e e

-- n = 17
    a b c d e a b c d e a b c d e
a b c c c c c d d d d d e e e e e

-- n = 21
  a b c d e a b c d e a b c d e a b c d e
a b b b b b c c c c c d d d d d e e e e e

-- n = 25
a b c d e a b c d e a b c d e a b c d e a b c d e
a a a a a b b b b b c c c c c d d d d d e e e e e

Here, we have completely saturated the 2-sequence permutations, yielding 25 of them, and cannot backtrack anymore. When backtracking fails, we simply augment the last trie, deepest:

-- n = 26
                                                a b
a b c d e a b c d e a b c d e a b c d e a b c d e e
a a a a a b b b b b c c c c c d d d d d e e e e e e

And we go on. Here, you can see a repetition of the same key, such as e e e e, but because those are tries, they are going to be actually encoded as a single node, having several children. Consider this example:

-- encode these permutations
--
--         a b c d
-- a b c d e e e e

local trie = {
  {
    key = 'a';
    trie = {}
  },
  {
    key = 'b';
    trie = {}
  },
  {
    key = 'c';
    trie = {}
  },
  {
    key = 'd';
    trie = {}
  },
  {
    key = 'e';
    trie = {
      { key = 'a'; trie = {} },
      { key = 'b'; trie = {} },
      { key = 'c'; trie = {} },
      { key = 'd'; trie = {} },
    }
  }
}

Two interesting properties about this algorithm:

• It does distribute permutations more equitably across your buffer as the number of permutations to generate grows, but will do it from the end of tries, making the first permutations the shortest as long as possible.
• When tries are saturated, we can lose 1-sequence permutations, but such a scenario authorizes to jump anywhere with only 2-sequence permutations.

Conclusion

This new algorithm was a lot of fun to come up with, design, test, implement and eventually use, because yes, it is already available (as a default) in hop.nvim. If for any reason you would prefer to use the first one, you can still change that in the user configuration (see :h hop-config-perm_method). Another point, too: since the support for the setup workflow, it’s been possible to locally override Lua function calls opts argument. You can then make a key binding using the first algorithm and another one using the new one – all this is explained in the vim help page 😉. It’s up to you!

Keep the vibes!

• — Day 16: Packet Decoder — // reflections
  • Header parsing
  • The encoding problem
  • The other encoding
  • Bit packing solution
  • Packed next_bits
  • Decoding a literal packet
  • Parsing operators
  • Part 1: summing packet headers’ versions
  • Part 2: evaluating the expression

— Day 16: Packet Decoder — // reflections

This problem doesn’t look too hard at the first glance, but has some hidden complexities than I thought pretty interesting. Just to sum up if you don’t want to open the link, the first part requires you to parse a hexadecimal number and interpret its binary representation as a packet, like what you would find in a network packet format, basically. You need to be able to parse correctly a single packet, which can contain nested packets. In this puzzle, packets represent expressions, that can either be:

• A literal number.
• An operation between packets.

Each packet have a header, comprising a header and its type (literal or operator), and then the actual data of the packet.

From this context, it seems pretty obvious to assume this is going to be a parsing problem. The first part asks you to parse the packet and its nested packets, and add all the version numbers of the headers of all packets. The format goes as this (quoting):

Every packet begins with a standard header: the first three bits encode the packet version, and the next three bits encode the packet type ID. These two values are numbers; all numbers encoded in any packet are represented as binary with the most significant bit first. For example, a version encoded as the binary sequence 100 represents the number 4.

Then, you have the description of a packet representing a literal number:

Packets with type ID 4 represent a literal value. Literal value packets encode a single binary number. To do this, the binary number is padded with leading zeroes until its length is a multiple of four bits, and then it is broken into groups of four bits. Each group is prefixed by a 1 bit except the last group, which is prefixed by a 0 bit. These groups of five bits immediately follow the packet header. For example, the hexadecimal string D2FE28 becomes:

110100101111111000101000
VVVTTTAAAAABBBBBCCCCC

Below each bit is a label indicating its purpose:

• The three bits labeled V (110) are the packet version, 6.
• The three bits labeled T (100) are the packet type ID, 4, which means the packet is a literal value.
• The five bits labeled A (10111) start with a 1 (not the last group, keep reading) and contain the first four bits of the number, 0111.
• The five bits labeled B (11110) start with a 1 (not the last group, keep reading) and contain four more bits of the number, 1110.
• The five bits labeled C (00101) start with a 0 (last group, end of packet) and contain the last four bits of the number, 0101.
• The three unlabeled 0 bits at the end are extra due to the hexadecimal representation and should be ignored.

So, this packet represents a literal value with binary representation 011111100101, which is 2021 in decimal.

I’m just going to focus on this first kind of packet because it’s already interesting.

Header parsing

From this description, if you have ever done bit parsing, you should already know that there is going to be a problem. You can parse a literal packet using this kind of pseudo code (ignoring errors for simplicity, it’s AoC!):

fn parse_packet(&mut self) -> Packet {
  let version = self.next_bits(3);
  let type_id = self.next_bits(3);

  match type_id {
    4 => todo!("literal parser"),
    _ => todo!("operator parser"),
  }
}

The big question is: how do we implement next_bits? Getting 3 bits of information? As you might know, the smallest amount of information a computer can manipulate is a byte, which is 8 bits, so… how do we manipulate less than that?

The encoding problem

I would like to say one thing before going on. The input is a hexadecimal string. The first step of your solution is to extract the binary representation. For instance, A (10 in decimal) is encoded as 1010 and 5A is encoded as 01011010. As you can see (might already know), hexadecimal is easy to parse into bytes: group hexadecimal digits by two, convert each digit to 4 bits, and glue them together. 5A is 5 -> 0101 and A -> 1010, which gives 01011010 as seen above.

But as we have seen with next_bits above, we will want to manipulate bits, not bytes. So you have several choices and design decisions to make here:

You can go the « easy » way and store each bit as a byte. This is very suboptimal, because you are going to waste 8 times the amount of memory you actually need to store all this. For instance, 5A (01011010), which is a single byte on your computer, will require 8 bytes to be stored: 00000000, 00000001, 00000000, 00000001, 00000001, 00000000, 00000001, 00000000. That is very inefficient, but it would work, if you put them in a Vec<u8>. To do that, you would basically need to read one hexadecimal digit at a time (which has 4 bits), and then perform bitwise right shifts with masking (& 0x1) to extract the bit. Something like:

fn inefficient_bit_extract(&mut self, four_bits: u8) {
  for i in 0..4 {
    self.bits.push((four_bits >> i) & 0x1);
  }
}

With this solution, implementing next_bits is easier, because you only need to pop the Vec<u8>. Let’s write next_bits with this kind of implementation. Because we do not need more than 15 bits in this puzzle (explained later in the puzzle text, not really important for now), we will return the read bits on u16:

fn next_bits(&mut self, n: usize) -> u16 {
  assert!(n < 16);

  let mut out = 0;

  for i in 0..n {
    out = (out << i) | self.bits.pop() as u16;
  }

  out
}

Let’s explain quickly.

    out = (out << i) | self.bits.pop() as u16;

This will extract a single bit, like 00000001, will convert it to 16-bit (so 0000000000000001) and will OR it to the number we are building. That number is left shifted at each iteration so that we only OR the least significant bit at each iteration. For instance, if we call next_bits(3) and we get 101, this implementation will basically store this in out at each iteration:

• End of 1st iteration: 0000000000000001.
• End of 2nd iteration: 0000000000000010.
• End of 3nd iteration: 0000000000000101.

Easy, and works.

The other encoding

However, I am a perfectionist. This is not satisfying to me, and it has been years since I have been wanting to implement something like what I am about to describe. I have been thinking about this problem with a different context but it is similar: a bool value, in a computer, is stored on the minimal amount of data a computer can manipulate: a byte. It means than storing a boolean value wastes 7 bits. If you have a single boolean value, there is nothing you can do. But if you need several boolean values, like, six booleans… using 6 bytes still wastes 42 bits for 6 bits of useful data! And 6 bits can hold in a single byte. So we should be able to store booleans in a packed array of bytes. The idea is the following: imagine that you want to store six boolean value in a byte:

00100101
ABCDEFGH

I have labelled each bit with a letter to make it easier to reference them. If you want to, for instance, the boolean value stored at index 2 (F in our representation), all you have to do is to right shift that number using the index of the element and 1-bit mask:

fn read_boolean(byte: u8, index: usize) -> u8 {
  assert!(index < 8);

  (byte >> index) & 0x1
}

If you want to set it, you need to do the opposite operation using a logical OR:

fn set_boolean(byte: &mut u8, index: usize) {
  *byte = *byte | (0x1 << index);
}

I wanted to use this AoC 18 day to encode my solution as a packed array of bits, and still have the next_bits interface that would allow me to get between 0 and 15 bits of data, encoded as u16. The catch is: because I bit pack the hexadecimal number, it is going to lie in a Vec<u8>. And the whole complexity relies in the fact asking for N bits can span across several bytes in the packed array…

Bit packing solution

The first thing we need to do is to think about the interface. I want that mutable next_bits interface. What it means is that I want to be able to read as many bits as I want (given less than 16 bits), I should not have to worry about the byte implications behind the scenes. The puzzle text clearly shows that when we are going to parse a literal value, we will have to read groups of 5 bits. Reading two literal numbers already implies two bytes (10 bits), and even the first group implies reading two bytes, because before that, you have the header on 6 bits (3 bits for the version, 3 bits for the type ID), living 2 bits to read for the beginning of the group, and 3 bits in the next byte to read. That’s a lot of complexity that should be hidden from the interface.

Let’s start with the Decoder type:

#[derive(Clone, Debug)]
struct Decoder {
  bytes: Vec<u8>,
  bitpos: usize, // the position in bit in the byte array
}

This is fairly simple: bytes is the bit-packed array I mentioned, and bitpos is the current position in that array. But it’s not the position in the array elements, it’s the position in bits. If bytes has 3 bytes (24 bits), then bitpos can be between 0 and 23. To know in which actual array element the bit is, we simply need to divide by 8. For instance, if bitpos = 17, then 17 / 8 = 2 tells us that the bit is in bytes[2]. To know the actual bit position in that byte, you will have guessed it, you need to take the modulo: 17 % 8 = 1, which is the second most significant bit. You can convert to least significant bit by subtracting that number to 8: 8 - 1 = 7.

With all that information, let’s fill the bytes:

impl Decoder {
  fn new(input: &str) -> Self {
    let digits: Vec<_> = input.chars().flat_map(|hexa| hexa.to_digit(16)).collect();
    let bytes = digits.chunks(2).map(|d| (d[0] << 4 | d[1]) as u8).collect();

    Self { bytes, bitpos: 0 }
  }

Here, because this is AoC, I don’t care about errors, and hence use flat_map to remove Option or Result in iterators. The important thing here is that I group hexadecimal digits by 2 (the .chunks(2) part), and then simply do this:

|d| (d[0] << 4 | d[1]) as u8

d[0] are the most significant 4 bits, so I left shift them by 4 bits, and d[1] is already correctly positioned, so nothing to do with it. I convert to u8 parse to_digit(16) yields u32.

Then, let’s implement next_bits.

Packed next_bits

  fn next_bits(&mut self, n: usize) -> u16 {
    // how many bits are still available from the current byte
    //
    // 0000000011111111
    //      ^ position is 5, so we have 3 bits still available
    let bits_avail = 8 - self.bitpos % 8;

    if bits_avail >= n {
      // we have enough in the current byte; compute the new position and right shift to align correctly
      let shift = bits_avail - n;
      let byte = (self.bytes[self.bitpos / 8] as u16 >> shift) & ((1 << n) - 1);
      self.bitpos += n;
      byte
    } else {
      // …
    }

The first step to do is to check whether the amount of bits requested would make us overlap with another byte given the current bitpos. If it’s not the case, then the problem is trivial. As shown in the example, we can just simply right shift by the number of available bits minus the requested amount (because we might still have room afterwards), and mask the N least significant bits. By the way, this is a funny one: setting to 1 the N significant bits. If you have N = 3, you want (on 8-bit here to simplify) 00000111. How do you make that quickly? It’s actually quite simple: what is this number? This 111? It’s an odd number (because its least significant bit is 1) and it looks like it’s almost 2³. It’s actually 2³ - 1. And this makes sense: remember in school / when you were learning binary that the biggest number you can represent on N bits is 2^n - 1. Like, on 8-bit, 2⁸ is 256, and the biggest number you can represent is 255, as you might already know, which is 11111111. So, we can simply deduce 00111…1 is the biggest number for 2^N where N is the number of 1. And that number is 2^N - 1. A power of 2, in binary, is a simple shift. So, 2^N is 1 << N. And `2^N

• 1is…(1 << N) - 1`. You have it.

We then increment bitpos by the number of read bits, and return the actual byte, for which the read bits are right shifted.

Now, what happens when bits_avail < n? We have to read bits_avail and shift them in the 16-bit output. Then we will have to switch to the next byte, and read n - bits_avail additional bits, because n is the requested number of bits to read and since we read every bits available from the current bytes, well, n - bits_avail. The « byte switching » logic can be a bit overwhelming at first but is actually not that hard: once we have read bits_avail, we know that the next byte will have 8 bits available. We can then divide the problem in two sub-problems, easier:

1. Read and shift 8 bits of data as long as n >= 8.
2. Read the remaining bits in the last byte.

This logic is implemented in the } else { branch, so I will just copy the else and put the code, and explain it:

    } else {
      // this is the annoying part; first, get all the bits from the current byte
      let byte0 = (self.bytes[self.bitpos / 8] as u16) & ((1 << bits_avail) - 1);
      self.bitpos += bits_avail;

      // then, left shift those bits as most significant bits for the final number
      let mut final_byte = byte0;

      // then, we need to get the remaining bits; compute the number of bytes we need
      let n = n - bits_avail;
      let bytes_needed = n / 8;

      // while we require more than 1 byte, the problem is trivial; just copy and left shift the bytes
      for _ in 1..=bytes_needed {
        let byte = self.bytes[self.bitpos / 8] as u16;
        self.bitpos += 8;
        final_byte = (final_byte << 8) | byte;
      }

      // the remaining bits can be extracted from the last byte
      let n = n % 8;
      let shift = 8 - n;
      let byte = (self.bytes[self.bitpos / 8] as u16 >> shift) & ((1 << n) - 1);
      self.bitpos += n;

      final_byte = (final_byte << n) | byte;

      final_byte
    }
  }

Let’s dive in.

      let byte0 = (self.bytes[self.bitpos / 8] as u16) & ((1 << bits_avail) - 1);
      self.bitpos += bits_avail;

This is the current byte, from which, as said earlier, we need to read all available bits. Because we are going to read everything from the current position to the least significant bit, we can just read the whole byte and apply a mask for the bits_avail least significant bits (remember the explanation earlier). So & ((1 << bits_avail) - 1) does the job. Because we have read bits_avail bits, we increment bitpos as well.

      // then, left shift those bits as most significant bits for the final number
      let mut final_byte = byte0;

This part is not strictly needed as I could have called byte0 final_byte in the first place, but I wanted a clear mind about what was doing what. The idea for the following steps is that we are going to accumulate bits in final_byte by left shifting it before applying the logical OR. The amount of shift to apply depends on the amount of bits read. For the case where we read a whole byte, we will just right shift by 8 bits.

      // then, we need to get the remaining bits; compute the number of bytes we need
      let n = n - bits_avail;
      let bytes_needed = n / 8;

This is a pretty straight-forward code given what I said above. n - bits_avail is the remaining amount of bits to read. bytes_needed is the number of full bytes we will have to go through (in self.bytes), and from which we will extract 8 bits each. The rest then makes more sense:

      // while we require more than 1 byte, the problem is trivial; just copy and left shift the bytes
      for _ in 1..=bytes_needed {
        let byte = self.bytes[self.bitpos / 8] as u16;
        self.bitpos += 8;
        final_byte = (final_byte << 8) | byte;
      }

Then, the remaining bits are the last part of the parsing problem. The idea is that we know we will have to read between 1 and 7 bits from that byte. That information is stored as n and shift:

      let n = n % 8;
      let shift = 8 - n;

We then extract the information, and return the N-bit number:

      let byte = (self.bytes[self.bitpos / 8] as u16 >> shift) & ((1 << n) - 1);
      self.bitpos += n;

      final_byte = (final_byte << n) | byte;

      final_byte

Decoding a literal packet

Armed with next_bits, the problem really becomes trivial. Let’s decode a literal packet and introduce the Packet type:

#[derive(Clone, Debug, Eq, PartialEq)]
struct Header {
  version: u8,
  type_id: u8,
}

#[derive(Clone, Debug, Eq, PartialEq)]
enum Packet {
  Literal {
    header: Header,
    value: u128,
  },

  Operator {
    header: Header,
    length_type_id: u8,
    packets: Vec<Packet>,
  },
}

And Decoder::decode:

impl Decoder {
  // …

  fn decode(&mut self) -> Packet {
    let version = self.next_bits(3) as u8;
    let type_id = self.next_bits(3) as u8;
    let header = Header { version, type_id };

    match type_id {
      // literal value
      4 => {
        let mut value = 0u128;
        loop {
          let bits = self.next_bits(5) as u128;
          value = (value << 4) | (bits & 0xF);

          if (bits >> 4) & 0x1 == 0 {
            break Packet::Literal { header, value };
          }
        }
      }

      // operator
      _ => {
        todo!()
      }
    }
  }
}

Some explanation. Given the format, we know that a literal number is made of packets of 5 bits, where the most significant bit does not belong to the number, but instead is a flag. If set to 0, it means that the literal is over.

          value = (value << 4) | (bits & 0xF);

This accumulates the 4 least significant bits of the 5 bits into the actual literal number.

          if (bits >> 4) & 0x1 == 0 {

And this performs the test on the most significant bit to check whether the literal number is fully built.

Parsing operators

Operators represent the other kind of packets, and are introduced, quoting:

Every other type of packet (any packet with a type ID other than 4) represent an operator that performs some calculation on one or more sub-packets contained within. Right now, the specific operations aren’t important; focus on parsing the hierarchy of sub-packets.

An operator packet contains one or more packets. To indicate which subsequent binary data represents its sub-packets, an operator packet can use one of two modes indicated by the bit immediately after the packet header; this is called the length type ID:

• If the length type ID is 0, then the next 15 bits are a number that represents the total length in bits of the sub-packets contained by this packet.
• If the length type ID is 1, then the next 11 bits are a number that represents the number of sub-packets immediately contained by this packet.

Finally, after the length type ID bit and the 15-bit or 11-bit field, the sub-packets appear.

There is nothing else to do than just applying those rules:

      // in Decoder::decode’s match on type ID

      // operator
      _ => {
        let length_type_id = self.next_bits(1) as u8;
        let mut packets = Vec::new();

        if length_type_id == 0 {
          let total_length_bits = self.next_bits(15) as usize;
          let mut bits_read = 0;

          while bits_read < total_length_bits {
            let bitpos = self.bitpos;
            packets.push(self.decode());
            bits_read += self.bitpos - bitpos;
          }
        } else {
          let sub_packets_nb = self.next_bits(11);

          for _ in 0..sub_packets_nb {
            packets.push(self.decode());
          }
        }

        Packet::Operator {
          header,
          length_type_id,
          packets,
        }
      }

Because of the next_bits interface, for when length_type_id == 0, we have no way to know deterministically when to stop, because we don’t really know how long each packet is. Because of this, the bits_read variable is introduced so that we know how many bits we read. That inforation is easy to get by comparing the value of bitpos before and after reading a packet. For the other branch, there is nothing interesting to comment here.

Part 1: summing packet headers’ versions

The first question was:

Decode the structure of your hexadecimal-encoded BITS transmission; what do you get if you add up the version numbers in all packets?

And my input was (it was a single string but I break it on several lines, because it’s pretty long):

60552F100693298A9EF0039D24B129BA56D67282E600A4B5857002439CE580E5E5AEF67803600D2E294B2FCE8AC489BAEF37FEACB31A678548034EA0
086253B183F4F6BDDE864B13CBCFBC4C10066508E3F4B4B9965300470026E92DC2960691F7F3AB32CBE834C01A9B7A933E9D241003A520DF31664700
2E57C1331DFCE16A249802DA009CAD2117993CD2A253B33C8BA00277180390F60E45D30062354598AA4008641A8710FCC01492FB75004850EE5210AC
EF68DE2A327B12500327D848028ED0046661A209986896041802DA0098002131621842300043E3C4168B12BCB6835C00B6033F480C493003C4008002
9F1400B70039808AC30024C009500208064C601674804E870025003AA400BED8024900066272D7A7F56A8FB0044B272B7C0E6F2392E3460094FAA500
2512957B98717004A4779DAECC7E9188AB008B93B7B86CB5E47B2B48D7CAD3328FB76B40465243C8018F49CA561C979C182723D76964220041275627
1FC80460A00CC0401D8211A2270803D10A1645B947B3004A4BA55801494BC330A5BB6E28CCE60BE6012CB2A4A854A13CD34880572523898C7EDE1A9F
A7EED53F1F38CD418080461B00440010A845152360803F0FA38C7798413005E4FB102D004E6492649CC017F004A448A44826AB9BFAB5E0AA8053306B
0CE4D324BB2149ADDA2904028600021909E0AC7F0004221FC36826200FC3C8EB10940109DED1960CCE9A1008C731CB4FD0B8BD004872BC8C3A432BC8
C3A4240231CF1C78028200F41485F100001098EB1F234900505224328612AF33A97367EA00CC4585F315073004E4C2B003530004363847889E200C45
985F140C010A005565FD3F06C249F9E3BC8280804B234CA3C962E1F1C64ADED77D10C3002669A0C0109FB47D9EC58BC01391873141197DCBCEA401E2
CE80D0052331E95F373798F4AF9B998802D3B64C9AB6617080

So:

1. Parse the input and decode it into a Packet.
2. Recurse on the version field of all sub-packets, summing them.

fn solve1(input: &str) -> u32 {
  let mut decoder = Decoder::new(input);
  checksum(&decoder.decode())
}

fn checksum(packet: &Packet) -> u32 {
  match packet {
    Packet::Literal { header, .. } => header.version as _,
    Packet::Operator {
      header, packets, ..
    } => header.version as u32 + packets.iter().map(checksum).sum::<u32>(),
  }
}

Yes, it’s that simple once you have made the right framework. :) Note that this function is not tail-recursive. A tail-recursive version would probably perform faster, but it was so convenient to write and took me 15s.

Part 2: evaluating the expression

Part 2 explains that the operator packets are actually expression operators, operating on literal values. Basically, it’s a whole AST. The rules are:

• Packets with type ID 0 are sum packets - their value is the sum of the values of their sub-packets. If they only have a single sub-packet, their value is the value of the sub-packet.
• Packets with type ID 1 are product packets - their value is the result of multiplying together the values of their sub-packets. If they only have a single sub-packet, their value is the value of the sub-packet.
• Packets with type ID 2 are minimum packets - their value is the minimum of the values of their sub-packets.
• Packets with type ID 3 are maximum packets - their value is the maximum of the values of their sub-packets.
• Packets with type ID 5 are greater than packets - their value is 1 if the value of the first sub-packet is greater than the value of the second sub-packet; otherwise, their value is 0. These packets always have exactly two sub-packets.
• Packets with type ID 6 are less than packets - their value is 1 if the value of the first sub-packet is less than the value of the second sub-packet; otherwise, their value is 0. These packets always have exactly two sub-packets.
• Packets with type ID 7 are equal to packets - their value is 1 if the value of the first sub-packet is equal to the value of the second sub-packet; otherwise, their value is 0. These packets always have exactly two sub-packets.

This is my solution:

fn solve2(input: &str) -> u64 {
  let mut decoder = Decoder::new(input);
  eval(&decoder.decode())
}

fn eval(packet: &Packet) -> u64 {
  match packet {
    Packet::Literal { value, .. } => *value as _,
    Packet::Operator {
      header, packets, ..
    } => match header.type_id {
      0 => packets.iter().map(eval).sum::<u64>(),
      1 => packets.iter().map(eval).product::<u64>(),
      2 => packets.iter().map(eval).min().unwrap(),
      3 => packets.iter().map(eval).max().unwrap(),
      5 => {
        if eval(&packets[0]) > eval(&packets[1]) {
          1
        } else {
          0
        }
      }
      6 => {
        if eval(&packets[0]) < eval(&packets[1]) {
          1
        } else {
          0
        }
      }
      7 => {
        if eval(&packets[0]) == eval(&packets[1]) {
          1
        } else {
          0
        }
      }

      id => panic!("unknown type id: {}", id),
    },
  }
}

And here you have it all. The complete solution is available on my GitHub repository for AoC 21. I don’t think it was the hardest problem, nor the more interesting, but the decision (and challenge) I decided to go with (bit-packing with a bit-driven interface) made the whole thing much more fun and interesting to me.

I hoped you liked it and that you learned something, especially regarding bitwise operations. That was pretty heavy! I think that you should also now have an idea about how you could write a specialized version of Vec<bool> that bit-packs booleans value. Obviously, we do not want Vec<bool> to actually do that kind of specialization behind the scenes (think FFI: when getting a *const bool or *mut bool from the Vec<bool>, if those pointers point to bit-packed data… it’s going to be a nightmare if the FFI function you use expect an actual array of unpacked boolean values).

For the rest of AoC, I’m probably going to continue working on it but I’m currently pausing at day 18 (Christmas, fatigue, a bit of OSS burnout too). I will probably write some more about AoC once I feel rested.

Have fun and keep the vibes!

Today I released a new version of warmy, the warmy-0.6.0 release. That release kicks in with a few additions, among:

• Complete rewrite of its internals, enabling optimizations (mostly about allocations).
• A nasty IO-bound bug was removed.

That bug caused long-lasting reloads on stream-copied resources go into weird behavior.

The bug

In order to get the bug, I must give a bit of context.

Imagine you have a large resource, like a 4K texture or a big mesh. Whenever your favourite software writes it to disk, it’s very likely it’ll stream chunks by chunks of bytes. For instance, it might choose to copy the resource 2 MB by 2 MB on disk. On each copy, your file system will generate WRITE events, that warmy will intercept. Before warmy-0.6.0, the default behavior was to reload the resource on the first WRITE event, which was already wrong, because only a very small part of the resource would have changed – I actually witnessed weird behaviors with textures in a demo of mine I’m working on, not seeing the new textures in my demo.

But there’s worse. There’s a parameter you can set of your Store, called update_await_time_ms. That parameter gives warmy a hint about how much time must have passed since the last update in order to effectively call the Load::reload function. However, this is a bit twisted, because if the resource takes more time to reload than update_await_time_ms, it’ll get repeatedly loaded – for as many as WRITE events were generated. This is a bit sick, yeah.

The fix

The fix was pretty simple: change the semantics of that update_await_time_ms. In 0.5.2, it has the default value of 1s, meaning that a resource wouldn’t reload if it was reloaded less than a second ago. The new semantics works on the future. Whenever a WRITE event is intercepted, warmy will call the Load::reload function only if no WRITE event is intercepted in the next update_await_time_ms. It’s a bit like the implementation of a click and a double click: you must wait a bit after you got a MouseRelease event in order to interpret is as a Click because another MouseRelease could arrive soon (generating a DoubleClick if it’s soon enough).

You’ll also notice that update_await_time_ms name sticks better to the new semantics!

In 0.5.2, the default value for update_await_time_ms was 1s. If we kept that value, it would result in a pretty bad overall latency. The value was lowered to 50ms instead.

You can still tweak that value if it doesn’t suit your needs.

More information can be found in the changelog.

On the future of the crate

I’ve been very happy with what warmy has brought to me so far. Other people also gave it a try and for now seem to enjoy it. I’ve gathered a few ideas for the future, based on IRL talks over a beer several beers, and GitHub issues / pull requests:

• We want to be able to pass around a context when loading and reloading. This would enable tweaking the loading behavior of the objects and pass values from the calling function. However, even though the feature is well-identified, it is not well-defined in warmy and more research must be done.
• Multithreading. There’re a few ideas I’d like to implement, like an IO thread that would do all the file IO-bound computation and dispatch the bytes to the other threads; and using Future.

Feel free to test it, and as always, keep the vibes!

This article is about two main topics:

• The new release of luminance and its changes.
• The introducing of ways to learn luminance (yay!).

If you don’t care about the changes, feel free to go read this to know how you can learn about luminance and graphics programming in general.

Motivation

Lately, luminance has received a wide range of feature additions, bug fixes and design ideas. I’ve been wanting to release all those changes as part of the 1.0 release but the thing is: among all the changes, some have been around on the master branch for months without a proper release on crates.io… because the 1.0 milestone was not reached. People have been moving towards luminance more and more and some provided feedback about using luminance. Happy but indecisive about what to do, I faced a dilemma:

• Either wait and release everything as part of 1.0 but eventually block people from using all the cool features of luminance because the last release on crates.io is months old.
• Break the feature set into two releases: 1.0 for everything and 0.31 for all the new candies.

I have decided to go with the second option.

luminance-0.31

Just before writing this article, the last luminance version was 0.30 — just for the record, that version is eleven months old, ~200 commits behind master. The new and most recent version is thus 0.31 and crates got updated:

• luminance-0.31
• luminance-windowing-0.3
• luminance-glfw-0.6
• luminance-derive-0.1, a new crate that brings procedural macros for the #[derive(..)] construct.
• luminance-glutin-0.1, a new crate supporting the glutin windowing crate. Currently, not all features are implemented but it’s usable.

Lot of work has been accomplished and I received several contributions from people all around the globe, including PRs and issues. I’d like to remind that I appreciate both and you are really encouraged to contribute in any way you want to. Special thanks fly to:

• @ambihelical
• @linkmauve
• @bobtwinkles
• @twetzel59
• And all others whom I discussed with and who provided feedback, especially on Reddit.

About that last point, my Reddit and Twitter interactions about luminance have been very interesting because I got to test the water about how people feel about luminance, especially when compared to (not so) similar crates, such as [gfx], glium or even gl. I came to the realization, after reading people and what they would love to have as a graphics crate, that luminance can have the role of the easy crate, that is not necessarily the fastest but fast enough to be quickly productive. I cannot help it but keep thinking about a simple question: if some people can make games in Java or C# with a garbage collector or using old tech like OpenGL 2.1 (yes, some people still make pretty good games with that), why would one need a perfect zero-cost abstraction down-to-the-metal unsafe ultra-optimized crate to write something? See, I went round and squares about that topic, because I’ve already used luminance in several projects of mine (mostly demoscene purposes), and it just does the job. So, yes, luminance doesn’t have that cool, new and modern Vulkan-type API, I must confess. But it has its own API, which is very functional-based (see the History section of luminance for further details about that) and, to me, modern enough so that people don’t get frustrated with the overall design being too clunky.

So, yeah. I gave up on the idea of introducing backends in luminance. I really changed my mind several times about that topic and it’s actually when I read comments on Reddit about people getting confused about the direction of the crate that I made up my mind: luminance must remain simple. Having a system of backends that can be hot-switched, concurrent etc. is just going to make things hard for people to use it — and maintain it! It’s likely that I will introduce, however, feature-gates to allow to compile luminance on WebAssembly via WebGL, OpenGL ES or even Vulkan at some point, but the difference is that no backend will be implemented. That means that those feature-flags aren’t likely to be summable at first. But all of this will be done in future releases; stay tuned.

The current blog post brings a description of all the changes of luminance-0.31. It should be the last 0.*.* version before hitting the 1.0 release. To the question:

Why not releasing 1.0 directly?

I answer that the 1.0 milestone has a backlog with two major changes that will take time to implement and I think it would be a pity to postpone a lot of great changes that are already available because of two features that are yet to be implemented. The concept of versions is to allow releasing features in a structured way without having to wait too much. So here we are.

This post also show cases a small tutorial about how to get started with luminance. The very first steps you should have would be to have a look at the examples/ directory and try to play with all of the samples.

Disclaimer: the following section of this article is based on luminance’s changelog.

Bug fixes

• Fix and remove panic! and attributeless renders.
• Various internal bug fixes and performance improvements.
• Fix pixel code for Format::R and Format::RG when querying a texture’s texels.

Major changes

• Remove the concept of GTup. No code was using it and it was not really elegant.
• Remove the uniform_interface! macro and replace it with the UniformInterface procedural derive macro.
• Buffer mapping is now always a mut operation. That is required to lock-in the mapped slices and prevent to generate new ones, which would be an undefined behavior in most graphics backends such as OpenGL.
• Change the framebuffer’s slots types and meanings. Those are now more natural to use (for instance, you don’t have to repeat the framebuffer’s associated types and dimensions nor even use the Texture<..> type anymore, as a type family is now used to ease the generation of color and depth slots).
• Change the way the Vertex trait is implemented.
  • The Vertex::vertex_format method has been renamed Vertex::vertex_desc.
  • Instead of returning a VertexFormat, that method now returns a VertexDesc. Where a VertexFormat was a set of VertexComponentFormat, a VertexDesc is a set of VertexBufferDesc.
  • VertexBufferDesc is a new type that didn’t exist back then in 0.30. It provides new data and information about how a vertex attribute will be spread in a GPU buffer. Especially, it has:
    • An index, allowing to map the vertex attribute in a shader.
    • A name, used by shader programs to perform mapping.
    • An instancing parameter, used to determine whether we want vertex instancing.
    • A VertexAttribDesc, the new name of VertexComponentFormat.
  • As said above, VertexComponentFormat was renamed VertexAttribDesc.
  • Vertex attribute can now be normalized if they are signed integral or unsigned integral. That is encoded in the VertexAttribType’s integral variants.
  • A new trait has appeared: VertexAttrib. Such a trait is used to map a type to a VertexAttribDesc.
  • Vertex has zero implementor instead of several ones in 0.30. The reason for that is that VertexBufferDesc is application-driven and depends on the vertex semantics in place in the application or library.
  • Vertex semantics are introduced in this release and are represented via the Semantics trait. Implementing directly Semantics is possible, even though not recommended. Basically, Semantics provides information such as the index and name of a given semantics as long as the list of all possible semantics, encoded by SemanticsDesc.
  • Users are highly advised to look at the Vertex and Semantics proc-macro derive in the [luminance-derive] crate.
• Revise the Tess type to make it easier to work with.
  • The Tess::new and Tess::attributeless functions were removed.
  • The TessBuilder type was added and replace both the above function.
  • That last type has a lot of methods that can be combined in different ways to build powerful situation of tessellations, among (but not limited to):
    • Normal and indexed tessellations.
    • Attributeless tessellations.
    • Tessellations with vertex instancing support.
    • Deinterleaved tessellations
    • Tessellations with support for primitive restart indexing.
  • Slicing was revised too and now has support for two new Rust operators:
    • The a ..= b operator, allowing to slice a Tess with inclusive closed bounds.
    • The ..= b operator, allowing to slice a Tess with inclusive bounds open on the left side.
  • Previously, the Tess::new associated function expected indices to be a slice of u32. This new release allows to use any type that implements the TessIndex trait (mapping a type to a TessIndexType. Currently, you have u8, u16 and u32 available.
  • Add Tess::{as_index_slice,as_index_slice_mut}. Those now enable you to conditionally slice-map the index buffer of a Tess, if it exists.
• Add support for generic texture sampling.
  • This new feature is supported thanks to the SamplerType trait, used as constraint on the Pixel::SamplerType associated type.
  • Basically, that feature allows you to bind a Floating texture without caring about the actual type. That is especially true as you typically use sampler2D in a shader and not sampler2DRGB32F.
  • Such a feature reduces the number of combination needed to refactorize code.
• Implement vertex attrib explicit binding. This is a huge change that is related to vertex semantics. Basically, in 0.30, you have to ensure that the layout (location = _) is correctly set to the right value regarding what you have in your Tess’ vertex buffers. That was both unsafe and terribly misleading (and not very elegant). The new situation, which relies on vertex semantics, completely gets rid of vertex locations worries, which get overrided by luminance when a shader program gets linked.
• Change boolean-like enums — such as DepthTest — variants from Enabled / Disabled to On / Off or Yes / No, depending on the situation.
• Move swap_buffers from GraphicsContext to Surface in [luminance-windowing].
• Switch to GenMipmaps instead of bool to encode whether mipmaps should be generated in texture code. That change is a readability enhancement when facing texture creation code.
• Make Dimensionable::zero_offset() a constant, Dimensionable::ZERO_OFFSET.
• Change the way cursor modes are encoded from bool to CursorMode.

Minor changes

• Add the [luminance-glutin] crate, the windowing crate support for glutin.
• Add the [luminance-derive] crate.
  • That crate provides several procedural derive macros you can use to easily implement all required traits to work with luminance. Especially, some traits that are unsafe can be implemented in a safe way with that crate, so you should definitely try to use it.
  • Current available proc-macros are:
    • #[derive(Vertex)]: derive the Vertex trait for a struct.
    • #[derive(Semantics)]: derive the Semantics trait for an enum.
    • #[derive(UniformInterface)]: derive the UniformInterface trait for a struct.
• Support for dynamic uniform queries. Those are used whenever you don’t know which variables will be used in a shader at compile-time. This might be the case if you’re writing a GUI tool or a video game that uses a custom scripting language / node-ish representation of shaders. That feature doesn’t break the already-in-place and great uniform interface but complements it. You can use a shader Program<_, _, ()> and still set uniform values by querying the uniforms dynamically. This feature also fully benefits from the strongly typed interface of Uniform<_>, so you will get TypeMismatch runtime error if you try to trick the type system.
• Add the std feature gate, allowing to compile with the standard library – this is enabled by default. The purpose of this feature is to allow people to use default-features = false to compile without the standard library. This feature is currently very experimental and shouldn’t be used in any production releases so far – expect breakage / undefined behaviors as this feature hasn’t been quite intensively tested yet.
• Add support for the R11FG11FB10F pixel format.
• Migrate to Rust Edition 2018.
• The WindowOpt now has support for multisampling. See the WindowOpt::set_num_samples for further details.
• Implement dynamic edition of windowing types properties. That allows to change data on-the-fly, such as the cursor mode.
• Introduce normalized texturing. That feature is encoded as pixel formats: any pixel format which symbol’s name starts with Norm is a normalized pixel format. Such formats state that the texels are encoded as integers but when fetched from a shader, they are turned into floating-point number by normalizing them. For instance, when fetching pixels from a texture encoded with R8UI, you get integers ranging in [0; 255] but when fetching pixels from a texture encoded with NormR8UI, even though texels are still stored as 8-bit unsigned integers, when fetched, you get floating-point numbers comprised in [0; 1].

Patch & misc changes

• Remove std::mem::uninitialized references, as it is now on deprecation path. Fortunately, the codes that were using that function got patched with safe Rust (!) and/or simpler constructs. It’s a win-win.
• Add the #[repr(C)] annotation on vertex types in examples. That is a bit unfortunate because such an annotation is very likely to be mandatory when sending data to the GPU and it should be done automatically instead of requiring the user to do it. That situation will be fixed in a next release.
• Add more CI testing.
• Update examples and made them available to the cargo run --example command. Read more here.
• Massive documentation rewrite (among the use of #![deny(missing_docs)]. The situation is still not perfect and patch versions will be released to fix and update the documentation. Step by step.
• Add design notes and documents in the repository.
• Massive dependencies update. Special thanks to @eijebong for his help!
• Add the 11-query-texture-texels example, which showcases how to query a texture’s texels and drop it on the filesystem.
• Add and update README files. Especially, the gitter link was removed and an IRC link was added. If you want to get help:
  • Server: irc.freenode.net
  • Channel: #luminance

Learning luminance

I also spent quite a lot of time and energy working on two ways to learn luminance:

• Examples.
• The official, brand new wiki.

So far, I’m writing articles and the wiki is going to be updated let’s say, every week, if I find enough spare time. You can also tell me what kind of stuff you’d like to learn and do.

The official documentation is up to date but is not as good as I expect it to be. I will be adding patches versions to 0.31 to update it.

I hope you like luminance and will make a good use of it. And of course, keep the vibes!

Actually, it’s from 0.25.2, but I’ll just talk about the latest patched.

That new release received several patches:

• The gl dependencies was updated to gl-0.10.0.
• A new uniform_interface! macro was added.

I’ll introce that uniform_interface! macro in this blog entry.

Auto derive free almost free

That macro was written to provide a smoother and better experience when writing types that will act as uniform interfaces in shader. For the record, when you create a Program<_, _, _> with luminance, the third type variable is called the uniform interface. You’ll be handed back a value of that type when your shader is being used. That will give you the possibility to send data to the sader prior to making any rendering.

The main idea is to have a type like this:

struct Common {
  resolution: Uniform<[f32; 2]>,
  time: Uniform<f32>,
  jitter: Uniform<f32>
}

If you build a program which type is Program<_, _, Common>, whenever you ask a pipeline to use that program, you’ll be handed a Common object so that you can access back the uniforms.

In order for that to happen, though, there’s a constraint: your type must implement a trait. That trait is UniformInterface. There’s no magic behind that – though, it can be a bit harsh to implement that trait. If you’re using luminance or plan to, I strongly advise you to try an impl that trait by hand first.

Anyway, after the fifth or sixth uniform interface you’ll have written, you’ll start to get bored of writing the same code every now and then. That’s the exact same feeling as for serializing and deserializing with serde: it’s interesting to do it by hand the first time, but it gets really, really annoying after a while.

So it’d be great to be able to automatically derive UniformInterface for your own types. There’re two solutions here:

1. Use procedural macros so that we can write something like #[derive(UniformInterface)].
2. Use standard macro_rules!.

(1) is great because it seems seamless when you use it – you already use #[derive(Clone, Debug, Eq, PartialEq, Etc)]. However, even though it’s doable to learn syn in order to parse the Rust token stream, it’ll require some time and patience while I wanted something quick to mockup the idea. For that, (2) is perfect, because regular macros are easy and if correctly written, shouldn’t add too much weirdness over the type.

The idea is to move to (1) if I find (2) to be a success and really useful.

The macro

So… we’re talking about the uniform_interface! macro. This macro has already a pretty decent documentation, so feel free to visit it, but I’ll explain more here.

A macro is generally used to introduce an EDSL. For instance, nom’s do_parse macro uses a funny EDSL (you use operators like >> and return result with (…), which is not normal Rust code).

The uniform_interface! macro uses an EDSL that you know very well: it’s plain Rust code! Hot news: you’ll have nothing more to learn!

Note: it’s not really any Rust code, since you can only define structs. Then, see that as a subset of Rust.

The syntax is very simple. Let’s take back our sample from above with the Common interface but now let’s the macro do all the magic for us!

#[macro_use]
extern crate luminance;

uniform_interface! {
  struct Common {
    resolution: [f32; 2],
    time: f32,
    jitter: f32
  }
}

You’ll notice two interesting properties:

• You define your fields without annotating them with Uniform<_>: the macro does it for you.
• The UniformInterface impl is automatically generated for you!

The second point is the most interesting one, since it’s akin to writing #[derive(UniformInterface)]. As you can see, the syntax overhead is not really a problem.

The cool part of that macro is that it also supports Rust annotations on its fields. You have two possible annotations available:

• as("something") behaves by not using the field’s direct name and instead use the one provided as argument.
• unbound enables not to make the whole uniform interface fail if a field cannot be mapped on the GPU side.

The as(…) annotation is very simple and straight-forward to get, since it lets you change the binding name of the field. The unbound annotation is a bit trickier and you need to understand how UniformInterface expects the value to be constructed.

By default, when you try to map a field to something on the GPU side (shader program), you use the UniformBuilder::ask function. If you have a closer look at function, you can see that it returns Result<Uniform<T>, UniformWarning>. In order to get the Uniform<T> out, you’re left with the choice of how you should handle errors. And that will depend on how you want your value to be built. For instance, some fields might be completely mandatory for your shader to work and others optional. unbound tags a field as optional.

You can mix both annotations if you want to remap an optional field!

#[macro_use]
extern crate luminance;

uniform_interface! {
  // we want to export that, so we also make it pub
  pub struct Common {
    resolution: [f32; 2], // this is really required
    #[as("t")]
    time: f32, // will be referenced with "t" in the shader and is mandatory as well
    #[unbound, as("bias")]
    jitter: f32 // will be referenced with "bias" in the shader and is optional
  }
}

That’s all for today! I hope that feature will be useful for whomever uses luminance – I use it extensively and I’ve been using uniform_interface! for several days now and it’s really appreciated! :D

I plan to add another macro to create buffer types, since they must meet GPU-specific alignment rules, who are boring to maintain without code generation.

Feel free to provide feedback on Reddit or GitHub and have fun!

In a real time rendering system, it’s not uncommon finding constructs about assets. One famous construct is the resource manager. A resource manager is responsible of several tasks, among:

• providing a simple interface to load objects from disk (1) ;
• ensuring we don’t try to load the same object twice (2) ;
• resolving dependencies between resources (3).

The first point is obvious, but the two others are less intuitive. (2) is important when the user might try to load the same object several times – for instance, a car model, or a character or a weapon. The most known strategy to prevent such a situation from happening is by using a software cache.

A software cache – let’s just say cache – is an opaque object that loads the object on the first request, then just returns that object for future same requests. For instance, consider the following requests and the corresponding cache behavior:

1. load “wood.png” -> not cached ; loading ; return
2. load “grass.png” -> not cached ; loading ; return
3. load “wood.png” -> cached ; return
4. load “metal.png” -> not cached ; loading ; return
5. load “metal.png” -> cached ; return
6. etc.

That behavior is very nice because it will spare a lot of computations and memory space.

(3) is about dependencies. For instance, when you load a car model, you might need to load its textures as well. Well, not really load. Consider the following:

1. load “car.mesh” -> not cached 1. load “metal_car.png” -> not cached ; loading ; return 2. loading ; return
2. load “metal_car.png” -> cached ; return
3. load “other_car.mesh” -> not cached 1. load “metal_car.png” -> cached ; return 2. return
4. load “car.mesh” -> cached ; return

You got the idea. (3) needs (2) to be efficient.

Possible implementations

Singleton

In imperative languages and especially in those that support template and/or generics, people tend to implement the cache system with an ugly design pattern – which is actually an anti design pattern : singleton. Each type of resource is assigned a manager by using a template parameter, and then if a manager needs to load a dependency, it just has to reference the corresponding manager by stating the type in the template parameter :

Model & getResource<Model>(std::string const &name) {
  Texture &dependency = getResource<Texture>(...);
  ...
}

That way of doing might sound great, but eh, singletons are just global variables with a unicity constraint. We don’t want that.

Explicit pure store

We can use an explicit store object. That is, some kind of map. For instance, the store that holds textures would have a type like (in Haskell):

textureStore :: Map String Texture

A model store would have the following type:

modelStore :: Map String Model

And each stores is assigned a function; loadTexture, loadModel, and so on.

There are several drawbacks if we go that way. First, we have to carry all stores when using their functions. Some functions might need other stuff in order to resolve dependencies. Secondly, because of explicit state, we need to manually accumulate state! A loading function would have such a following type:

loadTexture :: Map String Texture -> String -> m (Texture,Map String Texture)

That will expose a lot of boilerplate to the user, and we don’t want that.

Implicit pure store

We can enhance the explicit store by putting it into some kind of context; for instance, in MonadState. We can then write loadTexture to make it nicer to use:

loadTexture :: (MonadState (Map String Texture) m,...)
            => String
            -> m Texture

There is a problem with that. What happens when we add more types? For instance if we want to handle textures and models? MonadState has a type family constraint that forbids two instances for the pair s m. The following is not allowed and will raise a compiler error:

instance MonadState (Map String Texture) MyState where
  ...

instance MonadState (Map String Model) MyState where
  ...

The solution to that problem is to have the carried state a polymorphic type and use typeclass constraint to extract and modify the map we want:

class HasMap a s where
  extractMap :: s -> Map String a
  modifyMap :: (Map String a -> Map String a) -> s -> s

With that, we can do something like this:

loadTexture :: (MonadState s m,HasMap Texture s,...)
            => String
            -> m Texture

loadModel :: (MonadState s m,HasMap Texture s,HasMap Model s,...)
          => String
          -> m Model

However, we hit a new issue here. What are s and m? Well, m doesn’t really matter. For simplicity, let’s state we’re using a monad transformer; that is, we use StateT s m as monad.

We still need s. The problem is that s has to be provided by the user. Worse, they have to implement all instances we need so that the loading functions may work. Less boilerplate than the explicit store solution, but still a lot of boilerplate. Imagine you provide a type for s, like Cache. Expending the cache to support new types – like user-defined ones – will be more extra boilerplate to write.

Closures

The solution I use in my engine might not be the perfect solution. It’s not referentially transparent, an important concept in Haskell. However, Haskell is not designed to be used in convenient situations only. We’re hitting a problematic situation. We need to make a compromise between elegance and simplicity.

The solution required the use of closures. If you don’t know what a closure is, you should check out the wikipedia page for a first shot.

The idea is that our loading functions will perform some IO operations to load objects. Why not putting the cache directly in that function? We’d have a function with an opaque and invisible associated state. Consider the following:

type ResourceMap a = Map String a

getTextureManager :: (MonadIO m,...)
                  => m (String -> m Texture)
getTextureManager = do
  ref <- newIORef empty
  pure $ \name -> do
    -- we can use the ref ResourceMap to insert / lookup value in the map
    -- thanks to the closure!

That solution is great because now, a manager is just a function. How would you implement getModelManager? Well:

getModelManager :: (MonadIO m,...)
                => (String -> m Texture)
                -> m (String -> m Model)
getModelManager loadTexture = ...

We can then get the loader functions with the following:

loadTexture <- getTextureManager
loadModel <- getModelManager loadTexture

And you just have to pass those functions around. The cool thing is that you can wrap them in a type in your library and provide a function that initializes them all at once – I do that in my engine. Later on, the user can extend the available managers by providing new functions for new types. In my engine, I provide a few functions like mkResourceManager that hides the ResourceMap, providing two functions – one for lookup in the map, one for inserting into the map.

Conclusion

I truly believe that my solution is a good compromise between elegance and ease. It has a lot of advantages:

• simple to use ;
• simple to implement; you just have to play around with closures ;
• dependencies resolving is easy to add and hidden once the functions are generated ;
• little runtime overhead (due to closures, might be optimized away by the compiler though) ;
• can be easily extended by the user to support custom/new types ;
• if correctly used, implementations can replace IORef with TVar or similar objects for thread-safe implementations ;
• several replicated functions mean several stores (can be useful in certain cases).

The huge drawback I see in that solution is its opacity. There’s also no way to query the state of each cache. Such a feature could be added by proving a new function, for instance. Same thing for deletion.

I’m one of those Haskellers who love purity. I try to keep my code the purest I can, but there are exceptions, and that cache problem fits that kind of exception.

Feel free to comment, and as always, keep the vibe and happy hacking!

Well, pretty quickly! There’s – yet – no method to make actual renders, because I’m still working on how to implement some stuff (I’ll detail that below), but it’s going toward the right direction!

Framebuffers

Something that is almost done is the framebuffer part. The main idea of framebuffers – in OpenGL – is supporting offscreen renders, so that we can render to several framebuffers and combine them in several fancy ways. Framebuffers are often bound textures, used to pass the rendered information around, especially to shaders, or to get the pixels through texture reads CPU-side.

The thing is… OpenGL’s framebuffers are tedious. You can have incomplete framebuffers if you don’t attach textures with the right format, or to the wrong attachment point. That’s why the framebuffer layer of luminance is there to solve that.

In luminance, a Framebuffer rw c d is a framebuffer with two formats. A color format, c, and a depth format, d. If c = (), then no color will be recorded. If d = (), then no depth will be recorded. That enables the use of color-only or depth-only renders, which are often optimized by GPU. It also includes a rw type variable, which has the same role as for Buffer. That is, you can have read-only, write-only or read-write framebuffers.

And of course, all those features – having a write-only depth-only framebuffer for instance – are set through… types! And that’s what is so cool about how things are handled in luminance. You just tell it what you want, and it’ll create the required state and manage it for you GPU-side.

Textures

The format types are used to know which textures to create and how to attach them internally. The textures are hidden from the interface so that you can’t mess with them. I still need to find a way to provide some kind of access to the information they hold, in order to use them in shaders for instance. I’d love to provide some kind of monoidal properties between framebuffers – to mimick gloss Monoid instance for its Picture type, basically.

You can create textures, of course, by using the createTexture w h mipmaps function. w is the width, h the height of the texture. mipmaps is the number of mipmaps you want for the texture.

You can then upload texels to the texture through several functions. The basic form is uploadWhole tex autolvl texels. It takes a texture tex and the texels to upload to the whole texture region. It’s your responsibility to ensure that you pass the correct number of texels. The texels are represented with a polymorphic type. You’re not bound to any kind of textures. You can pass a list of texels, a Vector of texels, or whatever you want, as long as it’s Foldable.

It’s also possible to fill the whole texture with a single value. In OpenGL slang, such an operation is often called clearing – clearing a buffer, clearing a texture, clearing the back buffer, and so on. You can do that with fillWhole.

There’re two over functions to work with subparts of textures, but it’s not interesting for the purpose of that blog entry.

Pixel format

The cool thing is the fact I’ve unified pixel formats. Textures and framebuffers share the same pixel format type (Format t c). Currently, they’re all phantom types, but I might unify them further and use DataKinds to promote them to the type-level. A format has two type variables, t and c.

t is the underlying type. Currently, it can be either Int32, Word32 or Float. I might add support for Double as well later on.

c is the channel type. There’re basically five channel types:

• CR r, a red channel ;
• CRG r g, red and green channels ;
• CRGB r g b, red, green and blue channels ;
• CRGBA r g b a, red, green, blue and alpha channels ;
• CDepth d, a depth channel (special case of CR; for depths only).

The type variables r, g, b, a and d represent channel sizes. There’re currently three kind of channel sizes:

• C8, for 8-bit ;
• C16, for 16-bit ;
• C32, for 32-bit.

Then, Format Float (CR C32) is a red channel, 32-bit float – the OpenGL equivalent is R32F. Format Word32 (CRGB C8 C8 C16) is a RGB channel with red and green 8-bit unsigned integer channels and the blue one is a 16-bit unsigned integer channel.

Of course, if a pixel format doesn’t exist on the OpenGL part, you won’t be able to use it. Typeclasses are there to enforce the fact pixel format can be represented on the OpenGL side.

Next steps

Currently, I’m working hard on how to represent vertex formats. That’s not a trivial task, because we can send vertices to OpenGL as interleaved – or not – arrays. I’m trying to design something elegant and safe, and I’ll keep you informed when I finally get something. I’ll need to find an interface for the actual render command, and I should be able to release something we can actually use!

By the way, some people already tried it (Git HEAD), and that’s amazing! I’ve created the unstable branch so that I can push unstable things, and keep the master branch as clean as possible.

Keep the vibe, and have fun hacking around!

So here’s a quick article I can link in the super fresh TWiN, website I released a couple of days ago and that I hope will help with that kind of issues.

What can you do with Hop

Hop has been around for some time now. I created it back in February 2021, so roughly one year and a half. It has changed and evolved quite a lot ever since. New hint algorithm, new commands, a very big number of new options and features. I really recommand people to read the embedded documentation of Hop. Yes, completely. It took me time to write in a way that it will take you a couple of minutes only to read. So yes, do read it. Get the habit to read the embedded documentation of the plugins you install, especially after new updates. Or read TWiN from now on 😁.

The wiki, the wiki, the wiki!

Yes, Hop has a wiki. It’s available here and you should read a couple of pages from it:

• The “default” commands.
• Mastering advanced Hop. This part contains a couple of examples showing you how to use the various Hop Lua functions and options to create a really advanced motion platform.
• All the configuration options.

Because I know some people will not click on those links and will still open PRs trying to implement features that are already there, here is a non-exhaustive list of advanced things you can already do, out of the box, with Hop.

Recreate f, F, t and T

It’s in the wiki and super simple. For that, you just need three options:

• direction, which must be set with require'hop'.HintDirection.BEFORE_CURSOR or require'hop'.HintDirection.AFTER_CURSOR.
• current_line_only, a boolean.
• hint_offset, a super power allowing you to offset the actual jump off the jump target by a given number of characters.

So f is basically:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.AFTER_CURSOR,
  current_line_only = true
})

F is then:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.BEFORE_CURSOR,
  current_line_only = true
})

And in the same idea, t is:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.AFTER_CURSOR,
  current_line_only = true,
  hint_offset = -1
})

And T:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.BEFORE_CURSOR,
  current_line_only = true,
  hint_offset = -1
})

Jump at the end of things

Hop already can already understand the concept of beginning and end of a jump target. It does not make sense with all of them, but for most, it can. That is implemented with the hint_position option, which has to be one of:

• require'hop.hint'.HintPosition.BEGIN
• require'hop.hint'.HintPosition.MIDDLE
• require'hop.hint'.HintPosition.END

So if you want to jump to the end of words:

require'hop'.words({
  hint_position = require'hop.hint'.HintPosition.END,
})

You can even jump right after the end of a word!

require'hop'.words({
  hint_position = require'hop.hint'.HintPosition.END,
  hint_offset = 1
})

Callbacks!

You can even use Hop to do something with the jump target that doesn’t imply jumping, like running a Lua function with the actual column and line where the hint is. It’s done with require'hop'.hint_with_callback.

Here, no example but an exercise for you: try to use require'hop'.hint_with_callback to send a notification (via vim.notify) displaying the jump target chosen by the user by hinting words. Tips: you will need to find the jump target generator for words.

Final recommendation

Please, feel free to read :h hop. It contains everything I just explained and so much more, like Hop extensions, multi windows, etc. Have fun hopping around!

Currently, Kakoune doesn’t support writing to files with a timeout, which could help. kak-tree-sitter is a UNIX server bridging Kakoune with tree-sitter, supporting semantic highlighting, text-objects, indent guidelines and more!

I want to use the opportunity of releasing kak-tree-sitter in version v0.4.0 to talk about what’s new but also explain a bit the new protocol used to make Kakoune communicate with the server and vice versa. I think it’s a pretty fun (and efficient!) way of making things, and it can give people ideas.

What’s new?

This new version adds a bunch of things to kak-tree-sitter. Among the interesting things:

• Add support for many languages by default in the shipped config.toml.
• Fix PID detection to make it easier to restart / fix the server in case of problems.
• Allow to specify the log level of the server.
• C-c support to stop the server if started as standalone.
• Remove tokio and replace with mio. It’s easier, faster and lighter.
• And obviously, rewrite the internals to use a new protocol.

Full changelog here.

Additionnaly, you get v0.4.1, which also brings some interesting changes:

• %opt{kts_lang} is now used to know how to highlight a buffer instead of %opt{filetype} directly. A hook automatically calls kak-tree-sitter-set-lang (which you can override) to set %opt{kts_lang} before talking to the server. By default, it simply forwards %opt{filetype}. The goal here is to allow people to provide their own filetype detection by overriding kak-tree-sitter-set-lang.
• Some more internal fixes.

New protocol?

So yes, the big improvement is the introduction of a new communication protocol between Kakoune and kak-tree-sitter. Before v0.4.0, the way things worked was:

1. The user typically starts the server from their kakrc, with a line such as eval %sh{ kak-tree-sitter --kakoune --daemon --session $kak_session }.
2. This blocks the editor while the server is starting. Because --daemon is passed, once the server is ready, it’s going to daemonize so that its main process exits and Kakoune gets control back.
3. The --kakoune argument does one important thing: it asks the server to send some data back to the editor, once the server is initialized. The data is sent back via the UNIX socket of Kakoune (kak -p). The session is known via --session $kak_session.
4. The data is basically a bunch of options, commands and hooks that automatically call back to the server when a buffer is opened with a supported filetype. Each command are wrapped in a %sh{} block, and uses the kak-tree-sitter -r interface to format requests as JSON.
5. For highlighting requests, the FIFO interface of Kakoune (i.e. kak_command_fifo and kak_response_fifo) is used to stream buffer content via write.

What was the issue with that? Well, all those %sh{} implied to open a shell everytime we wanted to perform a request to the server. And for highlighting, that happens very often (by default, the trigger hook runs for NormalIdle and InsertIdle, but you can easily imagine that it runs almost on all keypresses modifying the window or the buffer). That’s a lot. I quickly came to the realization that I wanted something… faster and with less layers.

See, this kak_command_fifo and kak_response_fifo are pretty interesting FIFO files. The idea is that Kakoune handles their lifetimes, and they work when you do shell expansions (i.e. %sh{}). You can write to the $kak_command_fifo Kakoune commands to be executed. This allows to execute Kakoune commands interleaved with shell commands. You can then use $kak_response_fifo to write back results from Kakoune. I used to write the content of buffers to $kak_response_fifo and pass the path to this FIFO in the highlight requests so that the server just had to read from the FIFO and provide the highlights back to Kakoune asynchronously, via kak -p.

FIFOs are wonderful because you can think about them as a 1-1 blocking rendez-vous point between a producer and a consumer. If a consumer arrives, it blocks until a writer arrives and starts writing, and a writer won’t write until a consumer arrives. FIFOs do not live on your disk, so writing to them (i.e. write syscall) is super fast and can be tought as memory-to-memory communication. It’s honestly pretty good.

However, we still have to open a shell to send the requests to the server with this approach… so I needed something else.

More FIFOs… MOOOOOORE!

The idea is actually pretty simple: we can use FIFOs to send requests, in the end. If we have one FIFO for each Kakoune session, we know that we should only have one writer (i.e. the Kakoune session), and we have a single consumer (the KTS server). Inside Kakoune, writing to files can be done with the echo -to-file and write command, and we don’t need a shell for that!

Now the important thing is that Kakoune doesn’t know the path to the FIFO to write requests to, so we still need a way to get that information. I had two different ideas:

1. We could standardize the place by using the session name. For instance, $XDG_RUNTIME_DIR/kak-tree-sitter/commands/$kak_session.
2. Or we could let the server send the path asynchronously, since a Kakoune starting session doesn’t know anything about the server initially.

Currently, this is done with the --kakoune flag. The data that is sent back to the editor contains options (e.g. %opt{kts_cmd_fifo_path}) so that we know where to write requests.

In the future, I might actually just standardize the location, since it’s not a random temporary directory.

The installed hooks, in the kak-tree-sitter group, will contain only a few options, mostly set in the global scope. The main hook is run whenever a new window is open on a given buffer. A FIFO request is made to KTS with the filetype (to be more correct, %opt{kts_lang}) and if KTS has the runtime files for this language (grammar, queries, etc.), it will send back more data to Kakoune, that will be set for the buffer scope. This code will contain the actual interesting hooks (e.g. NormalIdle and InsertIdle) that will make more FIFO requests to, for instance, highlightthe buffer.

The content of the buffer is streamed via a FIFO, too — %opt{kts_buf_fifo_path}. Using this pair of FIFOs, we can send requests to the server and stream buffer content by just using echo -to-file and write Kakoune commands. No more shell expansions on the hot path!

Note: currently, buffers must be entirely read by kak-tree-sitter because the diffing algorithm is done by tree-sitter-highlight, which was great as a PoC, but not ideal now. Partial updates using %val{history} and %val{uncommitted_modifications} are planned for a future release.

The only drawback of this approach is that, because we are writing to FIFO files… if one side of the channel is not there, the other side will block and hang. That could lead to Kakoune freezing (for instance, if you kill the server before trying to quit the editor). However, this is unlikely to happen and is an acceptable tradeoff to me.

Currently, Kakoune doesn’t support writing to files with a timeout, which could help.

Conclusion

This new release is exciting to me. I have learned many things, especially regarding mio vs. tokio (all of those FIFOs requires a lot of IO synchronization) and optimizing. This new pair of FIFO per session made me realize that, besides the initial “setup” that requires a shell, we can perfectly communicate with the external world by only writing to files. In UNIX, everything is, indeed, a file!

The next releases will focus on two main topics:

1. Optimizing even further highlighting, by streaming buffer updates instead of streaming its content. That will massively increase performance for large buffers.
2. New features! I plan on adding theming (the current situation is weird); semantic selections (of course) and… indent guidelines!

If you would like to know more about kak-tree-sitter, head over to the wiki, which is up to date with v0.4.1.

Have fun and keep the vibes!

I have a MSI GS60 Ghost Pro 2QE I’m very proud of. It’s sexy and powerful. It comes with a fancy and configurable backlit keyboard.

There’s a tool called SteelSeries Engine for Windows we can use to change the colors of the keyboard. It supports several features:

• changing colors of three parts of the keyboard (left, middle and right) ;
• changing modes (normal, breathe, wave, demo, gaming).

Unfortunately, that software doesn’t work on Linux, even with wine. I tried hard to make it work and never actually found a way to run it. Then, I decided to look for alternatives and… found nothing working.

Yesterday, I tried a node.js-powered tool called msi-keyboard. And it worked. However, the interface and user interface was not my cup of tea. I decided to dig in in order to understand how it works, and I decided to write my own tool with a decent interface.

HID access

The key idea is that such keyboards are just HID devices. As a Haskell programmer, I looked for something that would grant me access to such devices, but nothing was working. There’s a hidapi package, but it doesn’t work and has bugs.

I didn’t give up though. I wrote my own Haskell HID API binding, called hid. Several good things about it:

• it does work ;
• it’s simple ;
• I lately wrote a software using it.

Feel free to install and use it!

msi-kb-backlit

Then, I wrote another Haskell package, msi-kb-backlit. It might require super user rights to work. If you’re not a Haskeller, you can find installation details here.

Note: if you use Archlinux, you can directly download msi-kb-backlit through the AUR! Search for msi-kb-backlit with yaourt, or download the tarball.

The software has an embedded documentation to help you tweak with colors and modes. ;)

Feel free to use all those pieces of software. I made them with love for you all!

Enjoy your week end, and keep the vibe!

The orphan instance problem is a well known problem that I’ve discovered while designing code in Haskell years ago. According to the Haskell wiki:

An orphan instance is a type class instance for class C and type T which is neither defined in the module where C is defined nor in the module where T is defined.

If it’s a bit overwhelming for you, here it is rephrased: this problem happens whenever you try to create an instance of a typeclass C in a module that is not the module where C is defined for a type T while you’re not in the module that actually introduces that T type. Since it’s not possible to pick an instances by hand, GHC disables you from writing several instances for a same combination of typeclass and types.

GHC actually has a workaround for the problem: the {-# OPTIONS_GHC -fno-warn-orphans #-} pragma annotation (or the -fno-warn-orphans compiler switch). However, this is not recommended if you can find another way because you expose yourself to ambiguities there.

Because Rust also has types and typeclasses (traits), it doesn’t escape the problem very much. You still have orphan instances in Rust (called Orphan Rules). There’re scoped to crates though, not modules.

In this blog entry, I want to explore a specific problem of orphans and how I decided to solve it in a crate of mine. The problem is the following:

Given a crate that has a given responsibility, how can someone add an implementation of a given trait without having to use a type wrapper or augment the crate’s scope?

A harsh solution: type wrappers

The typical workaround to this problem is to use a type wrapper. It works by encapsulating the origin type into another layer of typing so that the compiler recognize it as a complete different type, allowing you to implement whichever traits you want. Rust has a nice feature added to that: if you implement the Deref and DerefMut traits, you’re given access to all the implementations of the source type via deref rules, which is pretty sick. This works if you’re writing a binary, because no one will ever use your type wrapper, only you (and your team mates, but you’ll never publish the type so you’re breaking the orphan problem). However, what happens if you’re writing a library?

You will expose a type that is not the source one, forcing people to wrap it again if they want to implement another feature. If your type has a very different form from the source one, it’s okay. However, if you want to stick to the original semantics and use cases, people might get confused, especially whenever they will write functions that accept as arguments the source type.

The problem explained in splines

splines is a crate that provides you with spline interpolation. You can interpolate values in several dimensions with several kind of interpolators (step, linear, cosine, etc.).

Clearly, the scope of splines is to provide math and curves types and functions, nothing more. However, I use them in spectra, a demoscene crate of mine, in which I need them to implement some serde traits in order to serialize and deserialize them. Are you starting to see the problem?

When I thought about where I should write the code to allow serialization / deserialization, I came across the realization that writing it directly in splines would add another set of dependencies for everyone, even people not using the serialization part of it. I was a bit unsatisfied with that. So I thought about “Why not just adding another crate, like splines-serde?” Obviously, that doesn’t work because of the orphan rules: you cannot write an implementation of a trait in a different crate than where the type or the trait is defined. Meh.

A limited solution yet a solution: feature-gated impls

So I came with an idea, that is not perfect, but fits my needs pretty well. Rust has that interesting concept of features, allowing for conditional compilation. cargo supports them in the manifest and even allows you to declare dependencies as optional. The combination of both features and optional dependencies is key here.

Step 1: the manifest

Let’s have a look at the current Cargo.toml manifest in order to get how it’s done – I’ll slice the upper part and only show the features-related part:

[features]
default = ["std", "impl-cgmath"]
serialization = ["serde", "serde_derive"]
std = []
impl-cgmath = ["cgmath"]

[dependencies.cgmath]
version = "0.16"
optional = true

[dependencies.serde]
version = "1"
optional = true

[dependencies.serde_derive]
version = "1"
optional = true

Here, you can see that we are using default features. That means that if you depend on splines in simple ways (for instance, by just giving a version string, i.e. splines = "0.2"), you’ll get those features enabled by default. In the splines case, you’ll get the "std" and "impl-cgmath" features by default.

Looking at the "std" feature, you can see that it doesn’t depend on anything else. That feature will just make the whole library use the std crate. If you disable it, you can compile splines with no_std.

The "impl-cgmath" has a dependency on cgmath and you can see that it depends on the "0.16" version and that it’s optional. What it means is that if you disable default features you will not depend on cgmath anymore and thus, you will not even download / compile the dependency.

If you look closely at that manifest, you also see a feature that must be set explicitly: "serialization". That feature depends on both serde and serde_derive, adding support for the serialization code we talked earlier.

All of that is great and cool but how do we write the impls based on that manifest?

Step 2: the conditional code

There’re no rules here and people will give different advices on how you should write conditional code. I tend to remain simple as long as the project is not too complex. splines is a pretty simple and small project, so let’s get things straight!

The first thing to do is to know how we can access the features in Rust code. This is easy: via attributes. Attributes in Rust are enclosed in square brackets preceded by a dash and bang – #![]. There’s an interesting attribute: cfg(). It gives access to the configuration of the project, for short. It may take several kind of parameters but we’re interested in only one: feature. The syntax is the following:

#![cfg(feature = "name_of_feature")]

This oneliner will evaluate the following block whenever the "name_of_feature" is set. If you want to evaluate a block if a feature is not set, you can use the not() combinator:

#![cfg(not(feature = "name_of_feature"))]

It’s a bit ugly, but it does the job.

One final and cool attribute we’ll be using: cfg_attr(). It takes two arguments: the first one is a regular parameter you’d give to cfg that gets substituted as a boolean expression (feature(…), not(feature(…)), etc.) and the second one is an attribute that will get set whenever the former argument gets substituted successfully. For instance, this:

#![cfg(not(feature = "std"))]
#![no_std]

Can be rewritten more elegantly as this:

#![cfg_attr(not(feature = "std"), no_std)]

For the rest, as #[] applies to the direct item after it, it’s easy to write conditional extern crate for instance:

// on no_std, we also need the alloc crate for Vec
#[cfg(not(feature = "std"))] extern crate alloc;

#[cfg(feature = "impl-cgmath")] extern crate cgmath;

#[cfg(feature = "serialization")] extern crate serde;
#[cfg(feature = "serialization")] #[macro_use] extern crate serde_derive;

The #[cfg_attr(…) is even nicer when wanting to insert attributes on a type definition, as with the Key type:

#[derive(Copy, Clone, Debug)]
#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
#[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
pub struct Key<T> { … }

If you want static ifs in the actual implementation, you can cheat and use blocks as they’re items!

Interpolation::Cosine => {
  let cp1 = &keys[i+1];
  let nt = normalize_time(t, cp0, cp1);
  let cos_nt = {
    #[cfg(feature = "std")]
    {
      (1. - f32::cos(nt * consts::PI)) * 0.5
    }

    #[cfg(not(feature = "std"))]
    {
      use core::intrinsics::cosf32;
      unsafe { (1. - cosf32(nt * consts::PI)) * 0.5 }
    }
  };

  Some(Interpolate::lerp(cp0.value, cp1.value, cos_nt))
}

And finally, the one we were looking for to solve our orphans problem:

#[cfg(feature = "impl-cgmath")]
impl Interpolate for Vector2<f32> { … }

That impl will only exist if the "impl-cgmath" feature is set! Sweet!

I have another ultra cool use of attributes used along with existential impl Trait, but that’ll be for another blog entry.

Keep the vibes!

See, the type of application you need to write to make a demo is a bit special. Most programs out there are often either oneshot or reactive.

• A CLI program, an encoder/decoder, a math equation solver or a script are often oneshot programs. You give them a list of inputs and parameters and they do something based on their inputs. They’re are most of the time non-interactive.
• Programs such as GUIs, editors, video games, simulations etc. are often reactive, meaning that they mostly sleep until an event happen (a key press, mouse movement, etc.). For some, sleeping is reduced because they have a lot to do (handling network connections, performing I/O operations, streaming audio, rendering frames to the screen, etc.).

That binary split is not absolute, of course. Some programs don’t belong to any of the two prevous sections (think of a driver, a firmware, etc.). For the purpose of this article, though, it will be enough.

At some extent, we could state that a demoscene production, a video game or a simulation are also reactive programs. They mostly react to time as well as user interaction, network events, etc.. About time, you could imagine dividing time passing with very small quanta and picture time as a virtual clock that ticks such quanta. Every time a new quantum of time is emitted, the whole simulation is notified and reacts. However, representing that problem this way is not necessarily the best idea. See, a function of time is often a continuous function and then, it has an output value for any value of its input that lies in its domain. That property is interesting for us as we can get a value at any time with an arbitrary precision (the boundary being the precision at which we can represent a number on a computer).

The thing is, the kind of program we want generates its own inputs based on, mostly, the speed at which the hardware it’s running on is able to render a complete frame. The faster the more accurate we sample from that continuous function. That is actually quite logical: more FPS means, literally, more images to sample. The difference between two images will get less and less noticeable as the number of FPS rises. That gives you smooth images.

The “challenge” here is to write code to schedule those images. Instead of taking a parameter like the time on the command-line and rendering the corresponding image, we will generate a stream of images and will do different things at different times. Especially in demoscene productions, we want to synchronize what’s on the screen with what’s playing on the audio device.

The overall idea

From my point of view, we need at least two mechanisms of synchronization:

• A high-level synchronization mechanism, to state how globally the application will behave. I also like to see that kind of mechanism as a discrete space problem. You don’t have values to interpolate or sample from but only several pure values to “jump” from one to another every time the simulation time passes a given point in time. This kind of synchronization will state things like:
  • When the application starts, display this scene and let it play for 3 seconds.
  • Then after 3 seconds, switch to this other scene for 5 seconds.
  • After 8 seconds, draw this nice little cube and make it crash into a plane for about 10 seconds. Repeat that scene once more.
  • End the application.
• A low-level synchronization system. That would be used for a movement, a color change, a camera change, etc. This kind of synchronization is, to me, a continuous space problem. It can be solved by sampling from a curve, for instance.

Both those problems are solved by two crates I wrote lately. Respectively, awoo and splines. This blog post is about awoo. splines already has its own dedicated articles here and here. Nevertheless, I will make another blog article about it because I have new ideas I will add to the crate to enrich the splines experience.

awoo and the if / else if problem

Taking on the example of the high-level synchronization described above, one can write quickly the following naive yet working snippet:

let mut time_ms: f32 = 0.;

loop {
  if time_ms <= 5. {
    // render scene 1
  } else if time_ms <= 8. {
    // render scene 2
  } else if time_ms <= 20. {
    // render scene 1 again
  } else if time_ms <= 25. {
    // render scene 3
  } else
    break; // quit
  }

  time_ms += 0.01; // 100 FPS
}

That code is typical in demoscene production when we have to rush or even if we have a few scenes to write. However, it has several problems:

• It’s not really elegant. All those ifs seem like naive and not necessary code.
• The more time passes, the more conditions and branching we will do. What it means is that even if it’s not noticeable (testing floating-point numbers like that is really fast so it won’t change much), it’s easy to get that the second scene requires two tests in order to be rendered while scene 3 requires four and scene 1 requires either one or three!
• We notice that, every time a condition evaluates to true, all the previous branches can be completely discarded — we don’t have to test them anymore! — because time will never go backwards in a simulation (that is a strong assumption and it’s not true if you’re debugging, but for a release application, it is).

So, how can we do better? The idea is actually pretty simple. We want a very simple form a finite-state machine. In our case, the states are just what’s inside our ifs; the initial state is the first scene being rendered and the transitions are a predicate on the current time. Straightforward, right?

The idea of awoo is exactly that: allowing you to write the previous code like this:

let windows = vec![
  Window::new(0., 5.).map(|_| println!("hey, it’s scene 1!")),
  Window::new(5., 8.).map(|_| println!("hey, it’s scene 2!")),
  Window::new(8., 20.).map(|_| println!("hey, it’s scene 1 again!")),
  Window::new(20., 25.).map(|_| println!("hey, it’s scene 3!")),
];
let mut scheduler = SequentialScheduler::new(
  SimpleF32TimeGenerator::new(0., 0.01),
  windows
);

scheduler.schedule();

The code is now declarative and easier to read. Internally, the SequentialScheduler used here will make a single test to know which code it has to run. The implementation is not the typical implementation you would find for a FSM (finite-state machine), which uses a graph, but it’s akin.

You might be wondering why we do that map stuff instead of creating a Window directly with the actions. The answer is simple: a Window doesn’t hold any actions. That allows for creating windows via JSON, for instance, without having to deal with closures (I have no idea how that would even be possible with JSON). The idea is then to zip your windows to your actions by using a hashmap, for instance. This following snippet showcases exactly that (fully available here):

const WINDOWS: &str = r#"
{
  "a": {
    "start": 0,
    "end":   3
  },
  "b": {
    "start": 3,
    "end":  10
  }
}"#;

let windows: HashMap<String, Window<f32>> = from_str(WINDOWS).expect("cannot deserialize windows");
let a = windows.get("a").unwrap().map(|t| println!("in a: {}", t));
let b = windows.get("b").unwrap().map(|t| println!("in b: {}", t));
}

What gets interesting is that you can write your own time generator to manipulate the simulation in other ways — and you can also use different schedulers regarding what you do with time. For instance, you can imagine implementing a time generator that gets time from a HTTP request, a keyboard, a network socket, etc. and then control your simulation with external stimuli.

What happens when the escape key is pressed and that you need to stop the simulation in order to quit? Simple: you need an interruptible scheduler. awoo offers that as well in this form:

use std::sync::mpsc::channel;

let (sx, rx) = channel();
let mut scheduler = create_your_scheduler();

scheduler.interruptible_with(move |_| {
  // here, the closure’s argument is the time at which the scheduler is checking for interruptions
  if let Ok(_) = rx.try_recv() {
    Interrupt::Break
  } else {
    Interrupt::Continue
  }
});

scheduler.schedule();

Here, we use the spinning loop of the scheduler to check for interruptions in a straight-forward way.

So far, I have to admit I haven’t digged the async, await and Future concepts in Rust too much. For a single reason: discussions around those concepts have been heated and I will wait for an official announcement of the feature. Schedulers, especially as simple as the ones in awoo, don’t necessarily requires such IO features but the interruptible feature might. To me, the current implementation of interruptible schedulers in awoo is sufficient, especially for animation purposes — I might even add that feature directly in awoo so that you don’t have to do it by hand.

About the scope of the crate

Currently, the crate’s scope is very narrow — and I actually like that. A tight and small scope implies a better visibility about what the crate must do and how it must do it. The crate is currently simple and it might get more and more complex stuff as needs appear. As I always tell other developers and engineers, I don’t like to overthink too much features I don’t even need. Obviously, it’s important to keep planning possible future additions… But not too much. This is why that crate’s scope, if augmented, will only and always revolve around the concept of scheduling animation code. It’s currently an experimental crate and I’m trying to write demos with it, so we’ll see what time thinks about it.

So that’s all for me for today. I hope you liked it. Keep the vibes!

Background knowledge: typeclasses and laws

In Haskell, we have a lot of typeclasses. Those are very handy and – in general – come with laws. Laws are very important and give hints on how we are supposed to use a typeclass.

For instance, the Semigroup typeclass exposes an operator ((<>)) and has an associativity law. If a, b and c have the same type T, if we know that T is a Semigroup, we have the following law:

a <> b <> c = (a <> b) <> c = a <> (b <> c)

If T is a Monoid, which is a Semigroup with an identity (called mempty), we have a law for monoids:

a <> mempty = mempty <> a = a

Those laws can – have – to be used in our code base to take advantage over the structures, optimize or avoid boilerplate.

The Default typeclass

In some situations, we want a way to express default values. That’s especially true in OO languages, like in the following C++ function signature:

void foo(float i = 1);

In Haskell, we cannot do that, because we have to pass all arguments to a function. The following doesn’t exist:

foo :: Float -> IO ()
foo (i = 1) = -- […]

And there’s more. Even in C++, how do you handle the case when you have several arguments and want only the first one to be defaulted? You cannot.

So, so… Some Haskellers decided to solve that problem with a typeclass. After all, we can define the following typeclass:

class Default a where
  def :: a

We can then implement Default and have a default value for a given type.

instance Default Radians where
  def = Radians $ 2*pi

instance Default Fullscreen where
  def = Fullscreen False

However, there is an issue with that. You cannot use Default without creating newtypes to overload them. Why? Well, consider the following Default instance:

instance Default Float where
  def = -- what should we put here?

Remember that, in Haskell, an instance is defined only once and is automatically imported when you import the module holding it. That means you cannot have the following:

-- in a module A
instance Default Float where
  def = 0

-- in a module B
instance Default Float where
  def = 1

-- in a module C
import A
import B

-- What instances should we use?

Hey, that’s easy. We just have to keep the modules apart, and import the one we want to use!

Yeah, well. No. No.

Orphan instances are wrong. You should read this for further explanations.

That’s why we have to use newtypes everywhere. And that’s boring. Writing code should always have a goal. When we write as much boilerplate code as real code, we can start thinking there’s something wrong. Worse, if we have more boilerplate than real code, well, something is terribly wrong. In our case, we’re introducing a lot of newtypes for only being able to use def at a few spots. Is that even worth it? Of course not.

Default is evil

The Default typeclass is evil. It’s shipped with default instances, like one for [a], which defaults to the empty list – []. It might be clear for you but why would I want to default to the empty list? Why not to [0]? Or a more complex list? I really doubt someone ever uses def :: [a].

Another reason why Default is wrong? There’s absolutely no law. You just have a default value, and that’s all.

bar :: (Default a) => a -> Maybe String

Can you say what the default is for? Of course you cannot. Because there’s no law. The instance has no real meaning. A default value makes sense only for the computation using it. For instance, the empty list makes sense if we glue it to the list concatenation.

We already have a lot of defaults

In base, there’re already several ways to express defaulted values.

The Monoid’s mempty is a way to express a default value regarding its binary operation ((<>)).

The Alternative’s empty provides a similar default, but for first-class types.

The MonadZero’s mzero provides a different default, used to absorb everything. That’s a law of MonadZero:

mzero >>= f = mzero
a >> mzero  = mzero

Those defaults are interesting because we can reason about. If I see mzero in a monadic code, I know that whatever is following will be discarded.

Conclusion

So please. Stop using Default. It doesn’t bring any sense to your codebase. It actually removes some! If you want to provide functions with defaulted arguments, consider partially applied functions.

data-default is a very famous package – look at the downloads! You can now have some hindsight about it before downloading it and ruining your design. ;)

Happy hacking. :)

Today is the end of May 2023. Helix has been my primary editor for months now. I haven’t come back to Neovim. In the previous article, I mentioned that I couldn’t give a fair opinion about Helix because I had just started using it. Today, I think I have enough experience and usage (5 / 6 months) to share what I think about Helix, and go a little bit further, especially regarding software development in general and, of course, editing software.

However, before starting, I think I need to make a clear disclaimer. If you use Vim, Neovim, Emacs, VS Code, Sublime Text, whatever, and you think that “Everyone should just use whatever they want”, then we agree and this is not the point of this blog article. The goal is to discuss a little bit more than just speaking out obvious takes, but please do not start waving off the topic because you think “Everyone should use what they want”. There is a place for constructive debate even there. If you start arguing, then it means you want to debate, and then you need to be ready to have someone with different arguments that will not necessarily go your way, nor your favorite editor.

Finally, if you think I haven’t used Vim / Neovim enough, just keep in mind that I have been using (notice the tense) Vim (and by extension, Neovim) since I was 15, and I’m 31, so 16 years.

I have wrote that blog article already three times before deleting everything and starting over. I think I will make another blog article about how I think about software, but here I want to stay focused on one topic: editors and development environments.

Helix

From a vimmer perspective, Helix is weird. It reverses the verb and the motion (you don’t type di( to delete inside parenthesis, but you type mi(d to first match the parenthesis and then delete). Then, you have the multi-selections as a default way of doing things; Helix doesn’t really have the concept of a cursor, which is a design it gets from Kakoune, and I’ll explain what it means and implies later.

Some vimmers publicly talked about it. ThePrimeagen, for instance, made a Youtube video about it where he basically just scratched the surface of the editor and “Hell it’s not Vim so it’s not really good”. He moved the video to private then but I’m sure you can just look for Tweets. Many Vim afficionados react that way, which is not a very serious way of trying out something new, especially if you happen to publicly talk about it to thousands of people. I think it’s not fair to both the tool (here, Helix) and the people reading you, unless you are one of those Vim zealots thinking you know everything better than everyone else and dismissing people’ points of views just because they are not the same as yours.

Anyway, that reputation didn’t hold me from trying out, and the way I try software is simple: just give in and accept to drop your habits and productivity. Of course, at work, I was still using Vim / Neovim, but switched to Helix on my spare-time projects.

There are many aspects to talk about with Helix. The first one is that, contrary to what people who haven’t really and seriously tried it, the difference with Vim is not only “reversed motion/verb and multi-cursors.” The first difference is the design and the direction.

Design and direction

Helix is an editor that natively integrates many features that are most of the time plugins in others editors (even in VS Code). The best examples here are tree-sitter, surrounding pairs ( being able to automatically surround regions of text with (, [, HTML tags, etc.), LSP UIs, fuzzy pickers, etc. This is a massive and important difference because of two main things:

1. Code maintenance.
2. User experience.

About code maintenance, having all of those features natively integrated in the editor means that you are 100% sure that if you get the editor to start, the features will work, and the editor developers will keep that updated within the next iteration of the editor. For instance, having tree-sitter natively implemented (Rust) in Helix means that the editor itself knows about tree-sitter and its grammars, highlights queries and features. The same thing goes for surrounding-pairs or auto-pairs, for instance. If the team decides to change the way text is handled in buffers, then the code for auto-pairs / surrounding-pairs will have to be updated for the editor to be releasable.

The user experience will then be better, because you get those nice features without having to start looking around for a plugin doing it, with the problem of chosing the right one among a set of competing plugins. Plus the risk of having your plugin break because it’s not written by the Helix team. Just install the software and start using those features.

For now, Helix ships with a bunch of powerful features that makes it usable in a modern environment:

• tree-sitter support for semantic highligthing, semantic selection and navigation, etc. That also includes a native support for getting grammars / queries from the CLI with hx --grammar.
• LSP support, both in terms of features (go-to, references, implementations, incoming / outgoing calls, diagnostics, inlay hints, etc. etc.) and in terms of UI. It’s the same UI for everyone.
• DAP support for debugging (experimental at the time of writing).
• Surrounding pairs.
• Auto pairs.
• Git integration (gutter diff on the right side of your buffer) and Git semantic object (go to next change, etc.).
• Registers and user-defined registers (like in Vim), along with macros (but you won’t need them, trust me).
• Native discoverability, including a command palette with every possible available commands, tagged with their keybindings.
• Many bundled themes (yes, catppuccin themes are there!).
• Snappier than anything else.
• Various integration with your system, including clipboards, external commands, etc.

There is also one (major) thing I want to talk about and that deserves its own section: configuration.

Configuration done right

Helix treats configuration the way it should be: as data. Configuration in Helix is done in TOML. There is no scripting implied, it’s only a rich object laid out as TOML sections. And this is a joy to use. For instance, this is my current Helix configuration (excluding keys remapping, because my keyboard layout is bépo):

theme = "catppuccin_macchiato"

[editor]
scroll-lines = 1
cursorline = true
auto-save = false
completion-trigger-len = 1
true-color = true
color-modes = true
auto-pairs = true
rulers = [120]
idle-timeout = 50

[editor.cursor-shape]
insert = "bar"
normal = "block"
select = "underline"

[editor.indent-guides]
render = true
character = "▏"

[editor.lsp]
display-messages = true
display-inlay-hints = true

[editor.statusline]
left = ["mode", "spinner", "file-name", "file-type", "total-line-numbers", "file-encoding"]
center = []
right = ["selections", "primary-selection-length", "position", "position-percentage", "spacer", "diagnostics", "workspace-diagnostics", "version-control"]

Notice the tree-sitter and LSP configuration. Yes. None.

This is so important to me. Because configuration is data, it is simple for Helix to expose it and present it to the user by reading the TOML file without caring about having any side-effects. Helix has a command line (:) where you can tweak those options dynamically. And you can dynamically reload the configuration as well.

Multi-selection centric

The major difference, even before the reversed motion/verb thing, is the fact that Helix doesn’t really have a cursor. It has the concept of selections. A selection is made of two entities:

• An anchor.
• A cursor.

The cursor is the part of the selection that moves when you extend the selection. The anchor, as the name implies, is the other part that stays where it is: it’s anchored. By default, you have only one selection and the anchor is located at the same place as the cursor. It looks similar to any other editor. Things start to change when you begin typing normal commands. Typing l, for instance, will move both the anchor and cursor to the right, making them a single visual entity. However, if you type w, the cursor will move to the end of the word while the anchor will move to its beginning, visually selecting the word. If you type W, the anchor won’t move and only the cursor will move, extending the selection. If you press B, it will move the cursor back one word, shrinking the selection. You can press <a-;> to flip the anchor and the selection, which is useful when you want to extend on the left or on the right.

This concept of selection is really powerful because everything else is based on it. Pressing J will move the cursor down one line, leaving the anchor on the current line, extending selected lines. Once something is selected, you can operate on it, with d, c, y, r, etc. For instance, wd will select the word and delete it. Jc will extend the selection with the next line and start changing. Selections in Helix are not just visual helps: they represent what normal editing operations will work on, which is a great design, because you can extend, shrink and reason about them in a much more seamless and natural way.

But it’s just starting. Remember earlier when I say that by default, you have only one selection? Well, you can have many, and this is where Helix starts to really shine to me. The first way to create many selections is to press C. C will duplicate your current selection on the next line. If you have the anchor at the same position as the cursor, pressing C will make it like you have another cursor on the next line below. For instance, consider this text:

I love su|shi.
But I also love pizza.

The | is our cursor (but also anchor). If you press C, you will see something like this:

I love su|shi.
But I als|o love pizza.

But as I had mentioned, C duplicates selections. Let’s say you started like this, < being the anchor and | the cursor:

I love <sus|hi.
But I also love pizza.

Pressing C now will do this:

I love <sus|hi.
But I a<lso| love pizza.

Once you have many selections, everything you type as normal commands will be applied to every selections. If I type f., it will set the anchor to the current cursor and extend the cursor to the next ., resulting in this:

I love sus<hi|.
But I also< love pizza|.

Press <a-;> to swap anchors and cursors:

I love sus|hi<.
But I also| love pizza<.

And then pressing B will do this:

I love |sushi<.
But I |also love pizza<.

Erratum: B is not defined to this behavior in a vanilla Helix. I have remapped it to the Kakoune behavior. It doesn’t change much to what I’m saying here, though.

Multi-cursor is then not only a nice visual help, but also a completely new way of editing your buffers. Once you get the hang of it, you don’t really think in terms of a single cursor but many selections, ranges, however you like to call them.

Getting more cursors

C is great, but this not something we usually use. Instead, we use features that don’t exist in Vim. I’m not entirely sure how to call those, but I like to call them selection generators. They come in many different flavors, so I’ll start with the easiest one and will finish with the most interesting and (maybe a bit?) obscure at first.

Matching matching matching!

The m key is Helix is a wonderful key. It’s the match key. It expects a motion and will change all your selections to match the motion. For instance, mia “matches inside arguments” (tree-sitter). Imagine this context:

fn foo(x: i32, y: |i32) {}

fn bar(a: String, |b: bool) {}

Press mia to get this:

fn foo(x: i32, <y: i32|) {}

fn bar(a: String, <b: bool|) {}

Then, for instance, press <a-;> to flip the anchor and the cursor:

fn foo(x: i32, |y: i32<) {}

fn bar(a: String, |b: bool<) {}

F, to select the previous ,:

fn foo(x: i32|, y: i32<) {}

fn bar(a: String|, b: bool<) {}

Erratum: same thing as with B; I have remapped it in my config. The default B doesn’t extend like this.

And just press d:

fn foo(x: i32) {}

fn bar(a: String) {}

It’s so logical, easy to think about and natural. Someting interesting to notice, too, is that contrary to Vim, which has many keys doing mainly the same thing, making things weird and not really well designed. For instance, vd selects the current character and delete it. vc deletes the current character and puts you into insert mode. s does exactly the same. Why would you have a key in direct access doing something so specific? If you want to delete a word, you either press vwd, or more simply in Vim, dw. All of that is already confusing, but it doesn’t end there. x deletes the current character, but x is actually cut, so if you select a line with V and press x, it will cut the line. Press Vc to change a line… or just S. What?

All those shortcuts feel like exceptions you have to learn, and it’s a good example of a flawed design. On the other side, Helix (which is actually a Kakoune design it’s based on), have a single character to delete something: d. Since the editor has multi-selections as a native editing entity, all of those situations will imply using the d key:

• Deleting the current character: d.
• Deleting the next word: wd.
• Deleting the current line: xd (x selects and extend the line).
• Deleting delimiters but not the content: md(.
• Etc. etc.

That applies to everything.

Selecting, splitting, keeping and removing

The design of editing in Helix (Kakoune) is to be interactive and iterative. For instance, consider the following:

  pub fn new(
    line_start: usize,
    col_start: usize,
    line_end: usize,
    col_end: usize,
    face: impl Into<String>,
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,|
      col_end,
      face: face.into(),
    }
  }

Let’s say we would like, to begin with, select very quickly every arguments type and switch them to i32. Many ways of doing that, but let’s see one introducing a great concept: selecting. Selecting allows you to create new selections that satisfy a regex. The default keybinding for that is s for… select (woah). s always applies to the current Selections (notice the use of plural, it will be useful later). We then need to start selecting something. Here, we can just press mip to select inside the paragraph, since our cursor is right after line_end:

< pub fn new(
    line_start: usize,
    col_start: usize,
    line_end: usize,
    col_end: usize,
    face: impl Into<String>,
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
      face: face.into(),
    }
  }|

We have the whole thing selected. Press s to start selecting with a regex. We want the arguments, so let’s select everything with : and press s: and return:

  pub fn new(
    line_start<:| usize,
    col_start<:| usize,
    line_end<:| usize,
    col_end<:| usize,
    face<:| impl Into<String>,
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
      face<:| face.into(),
    }
  } 

See how it created a bunch of selections for us. Also, notice that it selected face: face.into(), which is not correct. We want to remove that selection. Again, several ways of doing it. Something to know is that, Helix (Kakoune) has the concept of primary selection. This is basically the selection on which you are going to apply actions first, like LSP hover, etc (it would be a madness to have LSP hover applies to all selections otherwise!). You can cycle the primary selection with ( and ). Once you reach the one you want, you can press <a-,> to just drop the selection. However, we don’t want to cycle things. We want a faster way.

Let’s talk about removing selections. The default keybinding is <A-K>. However, here, our selections are all about the same content (the :). As mentioned before, pressing x will select the current line of every selections:

  pub fn new(
<   line_start: usize,|
<   col_start: usize,|
<   line_end: usize,|
<   col_end: usize,|
<   face: impl Into<String>,|
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
<     face: face.into(),|
    }
  } 

Let’s filter selection and remove the one matching a pattern. In our case, let’s remove selections with a ( in them: <A-K>\( and return:

  pub fn new(
<   line_start: usize,|
<   col_start: usize,|
<   line_end: usize,|
<   col_end: usize,|
<   face: impl Into<String>,|
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
      face: face.into(),
    }
  } 

Now press _ to shrink the selections to trim leading and trailing whitespaces:

  pub fn new(
    <line_start: usize,|
    <col_start: usize,|
    <line_end: usize,|
    <col_end: usize,|
    <face: impl Into<String>,|
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
      face: face.into(),
    }
  } 

Imagine that we have changed our mind and now we actually want to change the usize to i32. We can use the keep operator, which is bound to K by default. Press Kusize and return to get this:

  pub fn new(
    <line_start: usize,|
    <col_start: usize,|
    <line_end: usize,|
    <col_end: usize,|
    face: impl Into<String>,
  ) -> Self {
    Self {
      line_start,
      col_start,
      line_end,
      col_end,
      face: face.into(),
    }
  } 

Another possible way is to press susize to only select the usize directly, which might be wanted if you want to change them quickly to i32, for instance.

The last operation that I want to mention is splitting. It’s introduced with S and will spawn several cursors separated by a regex. For instance, consider:

let |array = [1.0, 20.32, 3., 4.35];

Let’s say you’d like to select the numbers. With the methods described above, it’s probably challenging. With the splitting command, it’s much easier. Put your cursor anywhere in the list and press mi[ to select inside of it:

let array = [<1.0, 20.32, 3., 4.35|];

Then simply press S, to split the selection into selections separated by commas. You should end up with this:

let array = [|1.0>,| 20.32>,| 3.>,| 4.35>];

Pressing _ will shrink the selections to remove leading and trailing spaces:

let array = [|1.0>, |20.32>, |3.>, |4.35>];

And here you have it! Now remember that you can combine all of this methods with semantic objects, like mif for inside functions, mat for around type, mia for inside arguments, and many more. Recall that you can do that on each selection, allowing for really powerful workflows.

Do I really use all that at work / spare time projects?

Hell yes. It’s a muscular memory thing. For instance, I oftentimes the need to not only replace occurrences of patterns, like fooN — with N being a number — into logger.fooN, but I often need to change the structure around those occurrences. And here, Helix really stands out. In Vim, you’d have to use a super ugly regex, completely blind, and eventually a macro. The interactive and iterative approach of Helix is so much more powerful to me. For instance, for the case described above: % to select the whole buffer, sfoo. to select foo with a single character afterwards, then return, clogger.foo to replace with logger.foo, and still in insert mode, <C-r>" to paste what was yanked by the c operation. Here, the default register, ", makes a lot of sense, because this register is local to each selection, making this replace operation trivial and interactive.

Another example is something like this:

const COLORS: [Color; 3] = [
  Color {
    r: 255,
    g: 0,
    b: 0,
  },
  Color {
    r: 0,
    g: 255,
    b: 0,
  },
  Color {
    r: 0,
    g: 0,
    b: 255,
  },
];

Imagine that you want to change every Color constructor to a function call, that does something like Color::rgb(r, g, b). Doing that interactively and iteratively in Helix is so easy. I’d put my cursor anywhere in that block, press mi[ to select everything inside [], then sColor<cr> to create three cursors on the Cursor, and from that moment, it’s just ping-pong-ing between normal mode and insert mode like you would do with a single selection. You will be using f, t, miw etc. select things but the idea is the same, and the three occurrences will be updated at once.

A simpler editor overall

Contrary to other famous editors and IDEs, Helix is not supposed to be extendable; it doesn’t try to solve more problems than it should (and you will see in the Kakoune section that we can even push that to another extreme). Something like Neovim is a bit of a disguised IDE. Yes, a vanilla Neovim with no plugins and no configuration is just a very basic (and I would dare say featureless) editor. It won’t have LSP working. It won’t have tree-sitter working either. Nothing for git integrated. Nothing for delimiters, nothing for pickers, nothing for any modern development. The power of something like Emacs, Neovim etc. is to build on extensibility.

I used to enjoy that, until I came to the realization that, perhaps, it would be great to put things into perspective: is extensibility something we actually want? What do we try to solve with it? Well, we extend tools to add new features and new behaviors. We extend things so that the native / core tool ships with minimal features but doesn’t prevent people from adding specific and customized capabilities.

Extensibility

But is extensibility the only way to achieve that goal? The thing with extensibility is that:

1. You have to build in advance for it. You cannot ship an editor without any extensibility support and expect it to be an emergent feature. You have to add a basic support for it, whether it’s a plugin system, a dynamic / relocatable system (.so / .dylib / .dll), a scripting language, a JIT, etc.
2. Extensibility is always walled.

The last point is important. Extending a software requires the environment to adapt to the specifities of what you’re extending, and that will require the environment to know about the specifities. Here, the environment could be anything outside of Neovim. What it means is that, you’re not going to use external tools, but you are going to use the interfaces, scripting languages, DSLs etc. of the tool you want to extend.

For instance, people might argue that extending Neovim is great because it only requires learning Lua, which is not specific to Neovim, but that it is not actually true nor acurate. You have to learn “Neovim Lua”, which is basically its own beast. It’s like the standard library, but for Neovim. It will provide you with APIs you can use — and only use — to add new features to Neovim.

The same argument can be made to any extensible editor. VS Code, Emacs, etc.

Composability

Another way to add features and behaviors is to add them externally, by leveraging the tools themselves and compose them instead of pushing more features into them. That vision is not very popular and famous and I’m not entirely sure why. For instance, Vim has vim-fugitive, a Git client for Vim / Neovim. It has 2k commits, between 8k-9k lines of code… and can be used only in Vim and Neovim. Yes, it extends and adds features inside those editors, but still. If at some point you decide to switch to another editor, you can forget about this plugin. This is even worse with something like magit, which is the best Git client I haver ever used. Yet I don’t use it anymore, because it’s an Emacs plugin. What a shame.

Now repeat that reasoning for all the plugins you use. That has led some people to just install as few plugins as possible and switch to composability.

Composability is the same concept as in code. You have two systems A and B doing thingA and thingB, and you write some piping glue code / script to connect both. People use many different languages to glue things together. Among the most famous approaches:

• Python.
• Perl, especially when dealing with filtering text.
• The shell, and especially any POSIX.2 compliant shell (no, don’t start talking about fish).

I have shell functions that I source when I start my shell; for instance, one called p, to switch to my spare-time projects:

p () {
  proj_dir=${PROJ_DIR:-~/dev}
  project=$(ls $proj_dir | sk --prompt "Switch to project: ")
  [ -n "$project" ] && cd $proj_dir/$project
}

This is a great example of composability, which composes the content of a project directory (the $PROJ_DIR environment variable, or ~/dev by default), with the sk fuzzy finder, and then changes the directory to whatever the user has picked. I use that script all the time to quickly move to my various projects.

Notice that, sk, fzf, etc. already are tools that implement fuzzy searching for arbitrary inputs. Tools such as find or fd, who are so far in my experience the fastest programs to look for stuff, can be composed with shell pipes as well and integrated into your work environment.

Then the question starts to appear: why do editors / plugins re-implement all of that to have it inside the editor? It’s pretty apparent in the Neovim community, but it often ends up with abandonware plugins, and harder to maintain editors.

While I was wondering about all that, I was getting pretty productive with Helix, enjoying its simpler design, data configuration, better editing features and overall way more stable experience. I remembered that most of the Helix design came from Kakoune. And I started to think about one (not so) crazy idea: should I have a look at Kakoune?

And let’s enter Kakoune.

Kakoune

As mentioned above, Helix is heavily inspired by Kakoune. The main difference, from the surface, with distance, is that Helix comes with more bundled features, like LSP, tree-sitter, pickers, etc. However, there are more (drastic) differences that I need to talk about.

The first thing is, again, the design. And for that, I really need to quote a part from the excellent design doc written by @mawww. The part that is the most interesting to me is, obviously, composability.

Being limited in scope to code editing should not isolate Kakoune from its environment. On the contrary, Kakoune is expected to run on a Unix-like system alongside a lot of text-based tools, and should make it easy to interact with these tools.

For example, sorting lines should be done using the Unix sort command, not with an internal implementation. Kakoune should make it easy to do that, hence the | command for piping selected text through a filter. The modern Unix environment is not limited to text filters. Most people use a graphical interface nowadays, and Kakoune should be able to take advantage of that without hindering text mode support. For example, Kakoune enables multiple windows by supporting many clients on the same editing session, not by reimplementing tiling and tabbing. Those responsibilities are left to the system window manager.

And this is one of the most important things about Kakoune to me. First, it goes into the direction I’ve been wanting for years (I’ll let you read my previous blog articles about editors and production environments; I’m basically saying the same thing). And second, it ensures that the native editor remains small and true to its scope, ensuring an easier maintenance, hence less bugs and more stable. Also, it doesn’t blindly ignore what everyone else is doing.

Let’s start with an example. Yes, Kakoune doesn’t have a fuzzy picker to pick your files. However, as mentioned above, it composes well with its environment. It does that via different mechanisms (shell blocks, FIFOs, UNIX sockets, etc.). Here, we can just use whatever we like to get a list of files, and let Kakoune ask the user which files to open. We then simply use the selected value and open it. In order to do that, you need to read the design doc to understand a couple of other things, such as the section about interactive use and scripting. Quoting:

As an effect of both Orthogonality and Simplicity, normal mode is not a layer of keys bound to a text editing language layer. Normal mode is the text editing language.

Typing normal commands in a .kak file is then the way to go. And then, coming back to the fuzzy picker example, here are three commands defined in my kakrc:

## Some pickers
define-command -hidden open_buffer_picker %{
  prompt buffer: -menu -buffer-completion %{
    buffer %val{text}
  }
}

define-command -hidden open_file_picker %{
  prompt file: -menu -shell-script-candidates 'fd --type=file' %{
    edit -existing %val{text}
  }
}

define-command -hidden open_rg_picker %{
  prompt search: %{
    prompt refine: -menu -shell-script-candidates "rg -in '%val{text}'" %{
      eval "edit -existing  %sh{(cut -d ' ' -f 1 | tr ':' ' ' ) <<< $kak_text}"
    }
  }
}

As you can see, it’s just about composing known and well written tools together. Another example? Alright. Kakoune doesn’t have splits, but I still want them. Let’s go:

## kitty integration
define-command -hidden kitty-split -params 1 -docstring 'split the current window according to the param (vsplit / hsplit)' %sh{
  kitty @ launch --no-response --location $1 kak -c $kak_session
}

## zellij integration
define-command -hidden zellij-split -params 1 -docstring 'split (down / right)' %sh{
  zellij action new-pane -cd $1 -- kak -c $kak_session
}

define-command -hidden zellij-move-pane -params 1 -docstring 'move to pane' %sh{
  zellij action move-focus $1
}

## tmux integration
define-command tmux-split -params 1 -docstring 'split (down / right)' %sh{
  tmux split-window $1 kak -c $kak_session
}

define-command tmux-select-pane -params 1 -docstring 'select pane' %sh{
  tmux select-pane $1
}

The design is not extensible: it’s composable, and all in all, it makes so much more sense to me.

Kakoune vs. the rest

If you are used to Helix, then Kakoune with a bit of configuration will feel very similar to Helix. Of course, you will have to look around for LSP and tree-sitter support. The way we do that is by adding external processes to interact with Kakoune servers / clients via UNIX sockets, FIFO pipes, etc.. Kakoune doesn’t know anything about LSP or tree-sitter, but you can write a binary in any language you want and send remote commands to control the behavior of Kakoune.

• For LSP: kak-lsp/kak-lsp
• For tree-sitter: phaazon/kak-tree-sitter (I’m stil working on it and it lacks documentation but is usable).

The interesting aspect with those tools is that, in theory, we could adapt them to make them editor independent. If more editors adopted the strategy of Kakoune (composing via the shell), we wouldn’t even have to write other binaries to add LSP / tree-sitter support, which is an interesting aspect.

I plan on writing a blog article detailing the design of kak-tree-sitter, because I think it’s a good source of knowledge regarding UNIX and tree-sitter.

Besides that, Kakoune is way more mature than Helix, in the sense that it has some specificities to some edge cases with multi-selection features (such as, what happens when you have multiple cursors inside text looking like function argument lists, and you type mia to select them, but some selections are actually not arguments? Kakoune will remove the mismatched selections, which is what we would expect, while Helix…… erm it’s complicated! but currently, it will keep the selections around, which is confusing and dangerous).

Kakoune has a wonderful feature called marks. Marks are different from what you have in Vim. They use a specific register to record the current selections and eventually restore them later, supporting merging selections and editing commands. An example that I love doing; imagine the following snippet:

Thank you to [@NAME](https://github.com/NAME) for their contribution.

Let’s say you want to have a cursor on each NAME. Easy, with s. You just select the whole thing (you can select the whole line with x for instance), then sNAME, return, then c to start changing with whatever you want.

Now, imagine this instead:

Thank you to [@](https://github.com/) for their contribution.

How do you insert at the same time at the right of @ and before the )? Getting two selections will be hard (or you will end up writing crazy regexes; remember, we are not using Vim anymore!). A super easy way to do it is to move your selection to @:

Thank you to [@|](https://github.com/) for their contribution.

Press Z to register the current selection (you have only one). Then move the cursor to the ):

Thank you to [@](https://github.com/|) for their contribution.

And then press <a-z>a to merge the current selection to the one(s) already stored. You end up with this:

Thank you to [@|](https://github.com/|) for their contribution.

Two cursors at the right places! This is extremely powerful and a feature that should arrive in Helix, but not sure exactly when.

A pretty other important thing to say about Kakoune is that it has a server/client design that allows to share session contexts. That is the main mechanisms used to implement native splits (via Kitty, tmux, whatever), but also many other features, such as project isolation, viewing the same buffers with different highlighters, etc. etc.

…but it’s not perfect

There is one important thing I need to mention. I have been playing with Kakoune for a while now, and I have been working on kak-tree-sitter for almost as long as I’ve been working Kakoune (couple of months). And there is one issue with the UNIX approach.

See, tree-sitter, LSP, DAP, git gutters, etc. All those things are pretty fundamental to a modern text editor. Externalizing them (Kakoune) is an interesting take, but I’m not entirely sure Kakoune is still doing it completely correctly.

The main problem is social intelligence. Because all tooling is now externalized, many people can come up with their own efforts. For instance, kak-lsp and kak-tree-sitter are completely separate projects, and they should remain that way (for many reasons; scopes, maintenance, dependencies, etc.). However, in order to operate on the editor contents, both programs must interact with the editor. That implies:

• Retrieving buffer contents.
• Performing some actions that can mutate (and overlap / hijack) each other.
• Insert hooks that might be incompatible between them.

This problem is important, because dumping the whole content of a big buffer to an external process is one thing, doing it for every different external processes is a massive overhead. Because I have read a bit the source code of kak-lsp, I know that we (kak-tree-sitter) are doing similar things: we do use FIFOs to write buffer content and communicate with our servers / daemons without going through the disk. But we are doing it that twice. And it’s just two projects; any dissociate projects needing to access the buffer content will probably perform similar things.

That is a massive problem to me and I’m not sure how I feel about it. I’m not against sending the content of a buffer via a FIFO to an externalized program — I actually think it’s a pretty good design —, but doing it for every integration… I’m not exactly sure what would be the best solution, but maybe something that would snapshot a buffer inside some POSIX shared memory (with mutable lock access if needed) could be one way to go. Honestely, I am not sure.

All of that to say that, the take of Helix is pretty good here, because all of those UNIX problems are not there in that editor: everything runs in the same process, inside the same memory region. I will come back to this problem with my next article on kak-tree-sitter and its design.

Conclusion

Today, I’m mainly using both Kakoune and Helix. Helix still has some bugs, even with tree-sitter (which my daemon doesn’t have, funnily!), so I sometimes use one or the other tool.

I have learned so many things lately, with both Helix and Kakoune (especially Kakoune, it made me love UNIX even more). All of that echoes the disclaimer I made earlier: yes, Vim and Neovim are good, but Kakoune and Helix are so much better to me. Better designs, better editing experiences, largely snappier, more confidence in the direction of the native code (because a much, much smaller codebase). Helix is written in Rust, Kakoune in C++, but what matters is the actual design. To me, Kakoune is by far the best designed software I have ever seen, and for that, I really admire the work of @mawww and everyone else involved in the project. My contribution to the Kakoune world with kak-tree-sitter is, I hope, something that will help and drive more people in. I will write another blog article about that, with the pros., cons. and tradeoffs. of composability in editors.

In the meantime, have fun and use the editor you love, but remember to have a look around and stay open to change! Keep the vibes!

I would like to thank @Taupiqueur, who played an important role into making me undersand Kakoune and eventually fall in love with — the editor, I mean! :)

Among all the new features of luminance-0.40, there is one that I think is worth explaining in details, because it’s… pretty cool. If you like type states, refinement typing and on a general level, strong typing, you should enjoy this blog article.

While working on luminance-0.40, I spent two weeks working on a feature that is going to have a huge beneficial impact on how people use luminance. I’ve been wanting to see what people think about it for a long time, because I think it’s both a very powerful feature and allows to do low-level memory stuff in a safe way via the type system. Without further ado, let’s dig in.

• The Tess type
  • Digression on interleaved and deinterleaved data structures
  • The Tess type… revisited
• The magic of type systems
• Deinterleaving compile-time dispatching
• Wrap it up

The Tess type

In pre luminance-0.40, it is possible to gather vertices inside a type called Tess (it stands for tessellation). That type is responsible for holding vertices to render them later. They might represent point clouds, triangle-based meshes, lines, etc. It contains several properties, but we are going to focus on three:

• The actual vertex data (i.e. the held vertices).
• Indices, that can be used to prevent duplicating vertices and index them to reduce the size of the mesh.
• Vertex instances, which are special data that are instance-dependent. In a graphics library or a graphics engine, an instance often refers to an instance of a template, a pattern, that is to be shared among instances: the instances simply add some specific values, like positions, colors, etc. Imagine in a simplistic video game a garden with trees: it’s likely that the trees (all of them) are rendered via a single draw call, which contains instance data that is going to customize each instance.

In luminance-0.39, vertices, indices and instances can be retrieved, both read-only on read-write, via a mechanism of GPU slicing: you ask luminance to give you a type with which you are able to use &[T] and &mut [T].

However… we have several problems. First, the type is Tess and is completely monomorphized. What it means is that if you create a Tess that contains vertices of type SimpleVertex with indices of type u8, that information is not encoded in the type system — it is actually encoded as a value that is read and checked at runtime! When you ask for a slice, for instance to mutate the content of the Tess, you have to use a function like Tess::as_slice<V> where V: Vertex, which expects you to pass the type of stored vertices — in our case, it would be SimpleVertex. What happens if someone passed the wrong type? Well, currently, luminance checks at runtime that the stored type is the right one, but this is both wasted checks and not a very elegant API.

The same applies to indices and instance data: you don’t see them in the type. What happens if you slice the indices with u32? Runtime checks.

Now, there’s also the problem of building. When you build a Tess, you have to pass the vertices to the TessBuilder type, using functions like TessBuilder::add_vertices. It works, but it’s not practical. More importantly: if you call several times that function, you will create something that is called a deinterleaved memory data structure. Let’s digress a bit about that.

Digression on interleaved and deinterleaved data structures

Interleaving and deinterleaving makes sense when we talk about several objects / items of a same type, laid out in memory — typically in arrays. Imagine a type, Vertex, such as:

struct Vertex {
  position: Point3D,
  color: RGBA,
}

If you take a vector of Vertex (Vec<Vertex>), you get a continuous array of properties in memory. If you represent that in memory, you have something similar to this for two vertices (padding omitted):

[x0, y0, z0, r0, g0, b0, a0, x1, y1, z1, r1, g1, b1, a1]

We say that the memory is interleaved, because you’re going to alternate between fields when iterating in memory. Everything is interleaved. This kind of memory is what happens when you put a struct in an array, slice, etc. and is perfectly suited for most situations (even on the GPU). However, there is a small (yet important) detail: when you iterate (for instance in a for loop) on that array, you’re going to ask your CPU / GPU to load a bunch of values at once. That is going to fill your cache lines. If at each iteration you need to use every fields of the vertex, then that situation is pretty convenient, because you’re going to have a bunch of fields cached ahead (cache hits).

However… imagine a loop that only needs to access the position field. What’s going to happen is that your CPU / GPU will still load the same data in cache lines: now you get colors in the cache that you don’t need and your loop will make more cache misses. What could have been better would have been to fill the cache lines only with positions. If we had, instead:

[x0, y0, z0, x1, y1, z1]
[r0, g0, b0, a0, r1, g1, b1, a1]

Those two vectors can then be used independently for each need. Because we only need positions, we can simply use the first position vector. Now, when the CPU / GPU is going to load something in the cache, it’s going to cache much more values that we are going to actually use: we get more cache hits and it’s playa party.

That kind of memory layout is called deinterleaved memory. The way we typically do that is by simply moving the fields out of the struct and make several arrays of each field.

People tend to use two terms to describe both layouts: AoS and SoA.

So… months years ago, I realized that and decided a needed I better plan. Especially, on luminance-0.39, the way you handle slicing deinterleaved data is… well, inexistent. You cannot slice such data because it was never supported.

The Tess type… revisited

The new type is the following:

pub struct Tess<B, V, I = (), W = (), S = Interleaved>
where ABunchOfThings;

As you can see, there are a lot of new things there:

• B: the new backend type variable that most types now have; used to forward backend implementations down the API.
• V: the vertex type. It’s the type of Vertex you have typically defined yourself using luminance-derive.
• I: the index type. Most of the time, you’ll use either u8, u16 or u32, depending on the kind of geometry you index.
• W: the vertex instance data. Because people might not want that, () is a good default, but if you really need it, you can basically use any Vertex type here, since vertex instance data must be part of a Semantics.
• S: the interleaving mode. Either Interleaved or Deinterleaved.

You will find the same type variables with the TessBuilder type.

The magic of type systems

The cool thing about that change is how it enabled me to yield much, much better APIs. Consider the previous API to create a deinterleaved Tess:

let direct_deinterleaved_triangles = TessBuilder::new(&mut surface)
  .add_vertices(TRI_DEINT_POS_VERTICES)
  .add_vertices(TRI_DEINT_COLOR_VERTICES)
  .set_mode(Mode::Triangle)
  .build()
  .unwrap();

Notice the two add_vertices. There is no type information checking and ensuring that:

• You are passing vertex data that are compatible with the Vertex type those fields correspond to.
• You can basically call add_vertices as many times as you want and get a big buffer in GPU memory that will make no sense.

Now, the new API looks like this:

let direct_deinterleaved_triangles = surface
  .new_deinterleaved_tess::<Vertex, ()>()
  .set_attributes(&TRI_DEINT_POS_VERTICES[..])
  .set_attributes(&TRI_DEINT_COLOR_VERTICES[..])
  .set_mode(Mode::Triangle)
  .build()
  .unwrap();

If you try to call set_vertices — the name got changed from add_vertices to set_vertices — on the builder you get from new_deinterleaved_tess, you will get a compilation error, because you cannot set vertices on deinterleaved tessellations: you need to set attribute vectors. The set_attributes has the information that you are doing that for a Vertex, so it can check the input data you pass and ensure it contains values which type is a field type used in Vertex. If not, you get a compilation error.

Most importantly: because of how vertices work in luminance, a field type is unique to a vertex: it doesn’t make sense to use twice the VertexPosition type. If you end up in such a situation, it means that your Semantics type lacks another variant — remember: vertex fields are basically semantics-based attributes. That leads to the possibility to automatically find out where exactly the data you provide needs to go inside the GPU tessellation.

The super cool part is that you can now slice deinterleaved tessellations by simply asking for:

• The slice of vertices.
• A slice of attributes.
• The slice of indices.

In our case, we have a deinterleaved tessellation, which means we cannot slice whole vertices. If you try to get a slice of Vertex, you will get a compilation error. However, we can retrieve slices of vertex fields. The way we do this is super simple: we simply call the tess.vertices() or tess.vertices_mut() methods. It will infer the type of slices you are asking to automatically slice the right GPU buffer. This is all possible because our types are unique as the vertex fields.

let positions = tess.vertices().unwrap(); // you have to check for errors normally
let colors = tess.vertices().unwrap(); // you have to check for errors normally

Remark: you need to have the types of positions and colors inferred by setting / reading / passing them around, or you will have to put type ascriptions so that vertices() know what fields you are referring to.

Deinterleaving compile-time dispatching

So let’s dig a bit into how all this works. The first thing you need to know is that deinterleaving — the raw concept — is really simple. If you have a type such as:

struct Foo {
  a: A,
  b: B,
  c: C,
}

We say that Vec<Foo> is the interleaved representation of the collection. The deinterleaved representation needs to have three vectors of fields:

vec_a: Vec<A>
vec_b: Vec<B>
vec_c: Vec<C>

In order for a Vertex type to be valid in deinterleaving contexts, we need to have that tuple of vectors representation. First, we need a mapping between Vec<Foo> to (Vec<A>, Vec<B>, Vec<C>). This is the role of two traits: Deinterleave<T> and TessVertexData<S>.

Deinterleave<T> gives, for T, the field rank for T. For instance:

• <Foo as Deinterleave<A>>::RANK == 0
• <Foo as Deinterleave<B>>::RANK == 1
• <Foo as Deinterleave<C>>::RANK == 2

This is mandatory so that we know exactly which GPU buffers will need to be read / written to when creating tessellations and slicing them. You don’t have to implement Deinterleave<T> by yourself: luminance-derive does that automatically for you when you create a Vertex type. Also, you might be tempted to think that this rank will be used inside the Vertex type to retrieve data, but since you cannot pass whole vertices… nah. Also, you shouldn’t assume ranks based on fields declarations in struct (rustc can re-order that).

Next is TessVertexData<S>. It associates an input type — the type of data a tessellation will receive at creation type — for S, for the implementor type. The easy one is TessVertexData<Interleaved> for V where V: Vertex. The associated type is simply Vec<V>, because interleaved geometry simply stores the vertices as a vector of the whole vertex type. Simple.

It gets more complicated when we talk about deinterleaved geometry. TessVertexData<Deinterleaved> for V where V: Vertex has its associated type set to… Vec<DeinterleavedData>. Indeed: there is no simple way with the current stable Rust (and even nightly) to know the full type of Vertex fields at compile-time here. However, don’t get it wrong: that Vec is not a vector of vertices. It’s a typically small set of attributes (vectors too). If you look at the definition of DeinterleavedData, you get this:

#[derive(Debug, Clone)]
pub struct DeinterleavedData {
  raw: Vec<u8>,
  len: usize,
}

Yep. Type erasure at its finest. When you pass deinterleaved data, the data is type-erased and passed as a big blob of bytes, glued with its original size (so that we don’t have to store typing information – this will be needed when slicing vertex attributes).

Implementing slicing with these traits and data types is now possible: we can add another trait that we will use to slice vertices, for instance (the backend::VertexSlice trait in luminance) and based on the type of T in Deinterleave<T>, we can go and grab the GPU buffer we want. For instance, in both the OpenGL and WebGL luminance backends, buffers are stored in a Vec<_>, so in order to know which one we need to lookup, we simple use the <Vertex as Deinterleave<T>>::RANK constant value (a usize) and we’re good to go. You need two other traits for vertex instance data (InstanceSlice) and vertex indices (IndexSlice), and you’re good to go.

Wrap it up

So, checking at compile-time deinterleaving, in luminance, is done by:

• Using a trait (Deinterleave<T>) to associate a rank to a field T in a data structure.
• Using a trait (TessVertexData<S>) to get the input type of a tessellation: either Vec<T> for the whole vertices, or Vec<DeinterleavedData> for a set of attributes).
• When asking for a typed slice, such as vertices_mut::<T>(), we basically simply require Deinterleave<T> for V so that we can get a RANK: usize. We can then, in the backend implementation, find the right GPU buffer and slice it. The reconstruction to a typed slice (&[T]) is statically assured by the length stored in the DeinterleavedData type and by the fact DeinterleavedData<T> is implemented for V.

A small note though. luminance — actually, I do that with all my code, whatever the language — considers a lot of operations unsafe. In this case, implementing Deinterleave<T> is unsafe. The reason is pretty obvious: you can implement Deinterleave<Whatever>, even if your vertex type doesn’t have a Whatever field. Doing so would yield a hazardous / undefined behavior when slicing the GPU buffer. luminance-derive takes care of implementing the unsafe interface for you.

I hope you have learned something new or gotten some ideas. Keep the vibes!

On the last weekend, I was at the Revision demoparty (Easterparty). It’s a meeting of friends and great people doing graphics, music, code and that kind of fun and pretty stuff. I didn’t release anything, but I’ve been working on a release for a while now, and I was lacking something in my engine: light shafts.

I know a few ways to do that. They almost all fall in one of the two following classes:

1. screen-space-based;
2. raymarching-based.

Both the techniques produce interesting images. However, the screen-space-based method produces bad results when you don’t look directly to the light – it may even produce nothing if the light is out of screen – and the raymarching-based is a step process that might generate artifacts and can be slow.

The idea I had is very simple. I haven’t tested it yet, but it’s planned for very soon. I’ll post images with benchmarks as soon as I have something on screen. I’m not sure it’s an unknown way to do it. I just haven’t found anything describing that yet. If you have, please leave a link in the comments below! :)

Volume extraction

The idea is the following. You need a depthmap. If you’re used to shadow mapping you already have a depthmap for your light. In order to simplify this, we’ll use the depthmap used for shadow mapping, but I guess it’s totally okay to use another depthmap – we’ll see that it could be even handier.

For each point in that depthmap is the distance – in a specific space coordinates system – of the corresponding point in world space to the position of the light. If you have the projection and the view matrices of the light, it’s easy to deproject the depthmap. What would we get if we deproject all the depthmap texels into the world space? We’d get the exact lit surfaces.

For a spot light, you can imagine the deprojected version of the depthmap as a cone of light. The “disk” of the cone will deform and shape as the lit environment. That’s the first part of the algorithm.

We have a points cloud. What happens if, for each deprojected texel – i.e. point – we draw a line to the position of the light? We get an actual lines field representing… photons paths! How amazing is that?! Furthermore, because of the depthmap sampling, if you look at the light and that an object is between you and the light, the photons paths won’t go through the obstructing object! Like the following image:

Of course, because of using raw lines, the render might be a bit blocky at first. If you know the laser trick¹ – i.e. quad-based lasers, you can apply it to our lines as well, in order to get better results. The first improvement is to disable depth test and enable additive blending.

Algorithm

In the first place, you need to generate the depthmap of the light. Then, you need to extract the volumetric shaft. You’ll need a vertex buffer for that. Allocate w*h elements, where w and h are the depthmap’s width and height. Yeah, a point per texel.