About

This page hosts the hg_sdf library for building signed distance functions (or more precise: signed distance bounds). Those are a very elegant and flexible representation of geometry that can be rendered or otherwise processed. Roughly, coded SDFs are to triangle meshes or voxels what vector graphics are to pixels.

Building them is not easy yet. This is a bit like writing svg files by hand. Except fun.

This lib is the one that we used ourselves to make 64k intros like the timeless and on, straight from our version control system. Much of what we learned from those productions ended up in here. This includes the following items:

• A Collection of distance functions for primitives: Boxes, cones, cylinders, tori, blobby balls, you name it. This is the boring part.
• An Assortment of space-folding operators. Get an infinite amount of objects for the price of 1.3!
• An Arsenal of boolean operators to combine objects. Add fancy bevels of all kinds where objects meet or create entire nontrivial new objects from seemingly nothing! Be the envy of your fellow sceners!

All info on this page (except for the screenshots) can also be found in the source code, which is the definitive source. It also contains a FAQ and instructions on how to use the individual functions.

Version history

• 2015-12-15 - Initial release
• 2016-01-02 - Website Update, more operators, better implementation:
  • More compact and branchless implementation of some ops, courtesy of @paniq, thanks! The stairs operator now behaves in a subtly different way (surface stays the same, only field inside changes). Comparison Image (top is new).
  • Added more examples of operators that are non-boolean (groove, tongue, engrave).
• 2016-01-04 - Trivial update: replace all sign with sgn, thanks to @SeargeDP.
• 2021-01-29 - Documentation update: Repair dead links, add BibTeX for citation.
• 2021-07-28 - Dual-license as MIT OR CC-BY-NC-4.0.

How to use this

1. Build some system to #include glsl files in each other. Include this one at the very start. Or just paste everywhere.
2. Build a sphere tracer. See those papers:
   • Sphere Tracing (available here)
   • Enhanced Sphere Tracing (contains HLSL sample code)
   • Improved Ray Casting of Procedural Distance Bounds
   The Raymarching Toolbox Thread on pouet can be helpful as well and contains links to many more resources.
3. Use the tools in this library to build your distance bound f(). Maybe watch this talk from nvscene 2015, where you can watch an earlier version of this library in action. Maybe actually read all the comments that we added to the code for you.
4. ???
5. Attend a Demoparty and win a compo.

Why use this?

The point of this lib is that everything is structured according to patterns that we ended up using when building geometry. It makes it more easy to write code that is reusable and that somebody else can actually understand. Especially code on Shadertoy (which seems to be what everybody else is looking at for "inspiration") tends to be really ugly. So we were forced to do something about the situation and release this lib ;)

Everything in here can probably be done in some better way. Please experiment. We'd love some feedback, especially if you use it in a scene production.

The main patterns for building geometry this way are:

• Stay Lipschitz continuous. That means: don't have any distance gradient larger than 1. Try to be as close to 1 as possible - Distances are euclidean distances, don't fudge around. Underestimating distances will happen. That's why calling it a "distance bound" is more correct. Don't ever multiply distances by some value to "fix" a Lipschitz continuity violation. The invariant is: each fSomething() function returns a correct distance bound.
• Use very few primitives and combine them as building blocks using combine operators that preserve the invariant.
• Multiply objects by repeating the domain (space). If you are using a loop inside your distance function, you are probably doing it wrong (or you are building boring fractals).
• At right-angle intersections between objects, build a new local coordinate system from the two distances to combine them in interesting ways.
• As usual, there are always times when it is best to not follow specific patterns.

How to cite this

Examples

Boolean Operators

fOpUnionRound

fOpUnionChamfer

fOpUnionColumns

fOpUnionStairs

fOpIntersectionRound

fOpIntersectionChamfer

fOpIntersectionColumns

fOpIntersectionStairs

fOpDifferenceRound

fOpDifferenceChamfer

fOpDifferenceColumns

fOpDifferenceStairs

fOpPipe

fOpEngrave

fOpGroove

fOpTongue

fOpFuckingBaroquePictureFrame

Domain Operators

pMod1

pModSingle1

pModInterval1

pModPolar

pMod2

pModMirror2

pMod3

Code