float HarmonicOscillator::Step()
{
   m_v -= m_v * m_zeta + m_x * m_omega;
   m_x += m_v;
   return m_x;
}

I have been fascinated by it because of how much is capable of do. It oscillates sinusoidally (and sounds good), it decays exponentially in a user defined length (one might expect frequency and decay to be tied together, not the case), amplitude can also be defined (which saves a multiplication in later stages), and… ok. There are cons like exploding at low sampling frequencies, tone frequency drifting on long durations, it always decays, but, look at it. It’s so short.

Here you can see it in action, with a little extra on top:

Proper introduction is that it’s an Harmonic Oscillator, also a Mass-spring-damper Model, more commonly known as “jiggle physics”, especially in video-games and related fields. Code above is a Semi-Implicit Euler implementation, I stitched it together from Precise Control over Numeric Springing by Allen Chou (2015), and The physics behind spring animations by Maxime Heckel (2020). Here is a comparison with Implicit Euler without me simplifying zeta and omega:

void SpringSemiImplicit(float &x, float &v, float x_target, float zeta, float omega, float h)
{
   v += -2.0f * h * zeta * omega * v + h * omega * omega * (x_target - x);
   x += h * v;
}

void SpringImplicit(float &x, float &v, float x_target, float zeta, float omega, float h)
{
   const float f = 1.0f + 2.0f * h * zeta * omega;
   const float oo = omega * omega;
   const float hoo = h * oo;
   const float hhoo = h * hoo;
   const float detInv = 1.0f / (f + hhoo);
   const float detX = f * x + h * v + hhoo * x_target;
   const float detV = v + hoo * (x_target - x);
   x = detX * detInv;
   v = detV * detInv;
}

Differences are stability and that I didn’t manage to tame the implicit form. If we are pursuing stability, here is an implementation that seems to tackle every single corner Spring-It-On: The Game Developer’s Spring-Roll-Call by Daniel Holden (2021). Price to pay tho, is that uses conditionals, trigonometric functions, and it’s long. However, we are doing audio here; code there is for procedural animations, and they truly need to survive wild frame-rate roller coasters.

Step() function

Here is my Step() function in context:

void HarmonicOscillator::Initialise(float sampling_frequency, float frequency, float decay_frames, float amplitude)
{
   // This Initialise() is incomplete,
   // m_omega, m_zeta, m_x, and m_v, are explained later
   m_zeta = 2.0f * m_zeta * m_omega;
   m_omega = m_omega * m_omega;
}

float HarmonicOscillator::StepWithSweep(float sweep)
{
   m_v -= m_v * m_zeta + m_x * m_omega * sweep;
   m_x += m_v * sweep;
   return m_x;

   // Chou's form:
   // m_v += -2.0f * h * m_zeta * m_omega * m_v + h * m_omega * m_omega * (x_target - m_x);
   // m_x += h * m_v;
   // return m_x;
}

float HarmonicOscillator::Step()
{
   m_v -= m_v * m_zeta + m_x * m_omega;
   m_x += m_v;
   return m_x;
}

Changes from Chou’s SpringSemiImplicit() aren’t that many. In StepWithSweep() the most noticeable one is that x_target is zero, thus deleted, this turns a spring model into an oscillator (audio signals should oscillate around zero). Done that, expressions omega * omega and 2.0f * zeta * omega are resolved at initialisation rather than every frame. Of the three h, time-steps, two are repurposed as sweep, and one deleted. This is what in game development is known as dt, delta time, generally used to counter frame-rate changes by scaling motion/animations. Here it’s scaling oscillation frequency, and only frequency (more on this later). By keeping the three original h we will also scale decay, and we don’t want that.

Finally, Step() only differs on assuming a sweep or time-step of 1, thus deleted.

Initialisation() function

Grab a cup of something; it looks like this:

void HarmonicOscillator::Initialise(float sampling_frequency, float frequency, float decay_frames, float amplitude)
{
   m_omega = (frequency / sampling_frequency) * M_PI * 2.0f;
   m_zeta = 1.0f - expf(logf(0.001f) / decay_frames);

   m_x = 0.0f;
   m_v = m_omega * amplitude;

   m_zeta = m_zeta * 2.0f;
   m_omega = m_omega * m_omega;
}

m_omega is usual frequency business, now m_zeta is far more interesting, it’s a non-standard half-life function to control decay. How does it work?, this talk is gold: Lerp smoothing is broken by Freya Holmér (2024), she covers it under “The Exact Damper” section.

What happens is that in the Step() function, the term m_v -= m_v * m_zeta is exponential. By using a m_zeta less than 1, m_v will approach zero without ever reaching it, with every step being smaller than previous one. We can see it by setting m_v = 1; m_zeta = 0.5 and iterating on it:

1. m_v = 1.0 - 1.0 * 0.5
2. m_v = 0.5 - 0.5 * 0.5
3. m_v = 0.25 - 0.25 * 0.5
4. m_v = 0.125 - 0.125 * 0.5
5. m_v = 0.0625 - 0.0625 * 0.5

It looks nice on a plot, our real problem then is to find a m_zeta from a desired number of steps, or audio frames. Enter this monstrosity: m_zeta = 1 - exp(log(0.125) / 3), it will give us a m_zeta value so in 3 frames we will be near or at 0.125, and it’s: 0.5, makes sense. What about 7 frames to be near or at 0.333?, it says that a m_zeta of 0.14537076 is required, let’s see:

1. m_v = 1.0 - 1.0 * 0.14537076
2. m_v = 0.854 - 0.854 * 0.14537076
3. m_v = 0.730 - 0.730 * 0.14537076
4. m_v = 0.624 - 0.624 * 0.14537076
5. m_v = 0.533 - 0.533 * 0.14537076
6. m_v = 0.455 - 0.455 * 0.14537076
7. m_v = 0.389 - 0.389 * 0.14537076
8. m_v = 0.333 - 0.333 * 0.14537076

Spooky. No more questions asked, it works. One wee tiny bitty problem tho, as said before, it approaches zero without ever reaching it, so to stop this the best solution is to simply do it at a tiny value. However that 0.001 in m_zeta = 1.0f - expf(logf(0.001f) / decay_frames) is not your typical EPSILON, it’s -60dB (decibels).

Finally, the rest. m_v = m_omega * amplitude is only a value to compensate for this part m_v -= (...) + this.x * this.omega in Step(), it can be zero, nothing oscillates in that case, and you can set it later.

One room in the elephant tho, suddenly the expression m_zeta = m_zeta * 2.0f lost a multiplication between the multiple Initialise() functions I presented here. What happened is me doing a last optimisation that Chou compensated it with a division, not a biggie. Finally, no way I’m questioning m_omega = m_omega * m_omega existence (nor the * 2.0f), my DSP brain is warning me that these are the coefficients of a filter, and filters are truly, truly spooky.

***

Should mankind use this?, is it just novelty code?. Good question. My main premise here is that two multiplications, two additions, and one subtraction, are doing a lot of stuff. Now, who in the XXI century is counting assembly instructions?. Also, I didn’t mention use-cases, nor results on how it explodes and when, oh well… see you later!, thanks for reading!.

Taking a face-centric approach, the problem to solve revolves around finding the vertices that form a particular face, done that, what remains is to repeat the algorithm through every face of the shape. It looks like this:

struct Face
{
   Plane plane; // Where this face lies
   bool visible;
   List<Vector3> vertices; // What we want to calculate
};

void CalculateVertices(List<Face>* faces)
{
   for (Face* f = faces->Data(); f < faces->End(); f += 1)
   {
      if (f->visible == false)
         continue;

      // Intersect plane where face lies against other planes
      for (const Face* f2 = faces->Data(); f2 < faces->End(); f2 += 1)
      {
         if (f == f2) // Not against ourselves
            continue;

         Line line;
         if (PlanePlaneIntersection(f->plane, f2->plane, &line) == false)
            continue;

         // Clip intersection line into a segment
         // (by intersecting against other planes, oh no)
         Segment segment;
         for (const Face* f3 = faces->Data(); f3 < faces->End(); f3 += 1)
         {
            if (f3 == f2 || f3 == f)
               continue;

            // Cyrus-Beck algorithm
         }

         // Extract vertices from intersection segment,
         // store them in 'f->vertices', also validate them, reorder, you name it
      }
   }
}

PlanePlaneIntersection is the typical algorithm borrowed from elsewhere that returns a line from the intersection of two planes. That done, we don’t want a line but a segment, so we clip it using Cyrus-Beck, which in my poor geometry understanding is a clever take on a line-plane intersection algorithm.

And you can stop reading here, I just wanted to point how the operation:

1. Grab one face
2. Intersect its plane against the plane of another face
3. Clip resulting line by (basically) intersecting it against all other planes
4. Repeat, go to 2 iterating all faces, then to 1 iterating all faces

Is absurdly fast.

For completeness here’s how Cyrus-Beck looks in place:

// Intersect plane where face lies against other planes
for (const Face* f2 = faces->Data(); f2 < faces->End(); f2 += 1)
{
   if (f == f2) // Not against ourselves
      continue;

   Line line;
   if (PlanePlaneIntersection(f->plane, f2->plane, &line) == false)
      continue;

   // Clip intersection line into a segment
   // (by intersecting against other planes, oh no)
   float t_min = -FLT_MAX;
   float t_max = FLT_MAX;

   for (const Face* f3 = faces->Data(); f3 < faces->End(); f3 += 1)
   {
      if (f3 == f2 || f3 == f)
         continue;

      // Cyrus-Beck algorithm
      const float denom = Dot(f3->plane.normal, line.normal);

      if (Equal(denom, 0.0f) == true) // Parallel
      {
         if (Dot(f3->plane.normal, line.origin) > f3->plane.distance)
         {
            // No only line is parallel, but is also outside this plane normal,
            // which means that in a convex body this line doesn't contribute to
            // overall shape
            goto outside_continue;
         }

         continue;
      }

      const float t = (f3->plane.distance - Dot(f3->plane.normal, line.origin)) / denom;

      if (denom < 0.0f)
         t_min = Max(t_min, t);
      else
         t_max = Min(t_max, t);

      if (t_max < t_min) // Line got trimmed out of existence
         goto outside_continue;
   }

   Segment segment;
   segment.a = line.origin + Scale(line.normal, t_min);
   segment.b = line.origin + Scale(line.normal, t_max);

   if (Length(segment.a - segment.b) < BIG_EPSILON)
   {
      // Intersection segment has basically zero length
      continue;
   }

   // Extract vertices from intersection segment,
   // store them in 'f->vertices', also validate them, reorder, you name it
   {
   }

outside_continue:
   continue;
}

Bit ugly unrolled like that, innit?, it can be abstracted. Anyway, Equal is basically fabs(x) < EPSILON, same intent with BIG_EPSILON, a small number appropriate for map editors (I’m using 0.5 since the minimum grid snap is 1 unit out there). Also, it shines the fact that we are dealing with convex shapes, as is extremely easy to remove intersections that don’t contribute to the overall shape. And finally a warning, all our faces here point outside, Cyrus-Beck will kick your dog or something if that isn’t the case (although a single condition should be enough to deal with it, may be the case that our planes come from a bad BSP splitting stage).

And since you are still here, there’s a little optimisation that can be done if you only need all vertices of the brush and no more than that. It exploits the fact that most of them are shared, so it only iterates over distinct pairs of faces:

// Make a bbox
for (const Face* f1 = faces->Data(); f1 < faces->End(); f1 += 1)
{
   for (const Face* f2 = f1 + 1; f2 < faces->End(); f2 += 1) // Important part
   {
      if (cyrus_beck.Initialise(*f1, *f2) != 0)
         continue;

      for (const Face* f3 = faces->Data(); f3 < faces->End(); f3 += 1)
      {
         if (f3 == f2 || f3 == f1)
            continue;

         if (cyrus_beck.Step(f3) != 0)
            goto outside_continue;
      }

      Segment segment = cyrus_beck.End();

      bbox.max = Max(bbox.max, Max(segment.a, segment.b));
      bbox.min = Min(bbox.min, Min(segment.a, segment.b));

   outside_continue:
      continue;
   }
}

Other approaches

This algorithm here is basically me trying to avoid the one proposed by Stefan Hajnoczi in .MAP files file format description, algorithms, and code (2001). It looks like this:

For i = 0 to NumberOfFaces - 3
{
   For j = i to NumberOfFaces - 2
   {
      For k = j to NumberOfFaces - 1
      {
         if ( i != j != k )
         {
            legal = true;
            newVertex = GetIntersection ( i, j , k );

            for m = 0 to NumberOfFaces - 1
            {
               // Test if the point is outside the brush
               if ( DotProduct ( Faces[ m ].normal, newVertex ) + Faces[ m ].d > 0 )
               {
                  legal = false;
               }
            }

            if ( legal )
            {
               Polys[ i ].AddVertex ( newVertex );
               Polys[ j ].AddVertex ( newVertex );
               Polys[ k ].AddVertex ( newVertex );
            }
         }
      }
   }
}

Rather similar. For most purposes it’s only one for more, and since brushes rarely have more than 6 faces I can imagine no performance impact at all.

Then there’s the algorithm written by God himself, John Carmack. Which sadly, I couldn’t understand except that he’s really careful on preserving “windings” (segments in a face?) through the entire map compilation (why not make it at a final stage?). Someone summarised it on quakewiki.org:

Starting with the edges and vertices of a huge cube (usually ranging from -4096 to 4096 in each dimension), the edges of the cube are intersected with the planes of the faces. Upon each intersection, new edges and vertices are generated that replace some of the old ones until all planes have been used.

So it seems that Carmack is treating brushes like marble/wood carving. That’s really calling for floating errors as it’s an iterative approach, something that Hajnoczi and I are avoiding quite elegantly.

***

And that’s all!, thanks for reading, see you later when I manage to write a BSP algorithm (maybe I will discover that I’ve been doing all this wrong).

Penatibus placerat mi senectus magna volutpat ligula interdum posuere velit platea ut, litora diam ad nostra dapibus laoreet eleifend pellentesque ultrices nulla viverra, dui class varius habitasse fames imperdiet aliquam egestas mauris luctus. Non hac dui senectus interdum est platea habitant proin tempor, sociis fusce ad eros neque cras quisque venenatis. Cubilia conubia purus turpis taciti luctus ligula risus imperdiet inceptos, interdum sociis ullamcorper felis quis metus scelerisque pellentesque, at feugiat ridiculus magna himenaeos faucibus per magnis.