.M3F File Format

Introduction

An M3F file is one formula for Mandelbulb 3D, a Windows program for drawing three-dimensional fractals by ray marching with distance estimates. Mandelbulb 3D loads every formula it finds in its M3Formulas folder and offers it in the formula tabs, where up to six can be chained into a hybrid. A formula whose name starts with an underscore is an add-on: it is only meant to be used inside a hybrid, not on its own. The files here were written for version 1.8.9 of the program.

The file is text, but the formula itself is not: it is 32-bit x86 machine code, written as hexadecimal digits in a [CODE] section. Around it are the options the program shows for the formula, constants the code uses, and the author’s description. The program’s readme says of these files that they are “readable and editable”, “but the formula itself is in machine code”, and warns that formulas from other sources deserve mistrust because they are pure machine code.

The first option line, .Version = n, is the version of the formula interface the code was written for. The 714 files on the machine this site was written on carry six different numbers, and the viewer reads each as a format of its own: the layout of the file is the same, but the code, the options and the distance-estimate settings seen with each number differ.

The extension .m3f is used by other programs too. This site tells the files apart by their content: a Mandelbulb 3D formula starts with the line [OPTIONS], has a [CODE] and an [END] line, and a .Version option. A file that does not read so is not shown as one. The companion parameter files of the same program, .m3p, are binary and a fixed size.

A .m3f file dropped on any page of this site opens in the explorer, which shows the sections of the text, the options as a table, the constants, the machine code as a disassembly in which each instruction is linked to its hexadecimal digits, and the description.

How the program reads the file

From the program’s source (LoadCustomFormula in CustomFormulas.pas, see Links), which agrees with the 714 files:

• The first line must be [OPTIONS]. Each option line is matched on its first five characters: .SSE2, .DESC (DEscale), .SIPO (SIpower), .RSTO (RStop), .SSE3, .SSSE (SSSE3), .SSE4 (SSE4.1), .VERS, .DEOP and .ADES (ADEscale), in any case. Any other line is an option written .<kind> <label> = <value>; the kind is one of 23 (Double, Single, Integer, DoubleAngle, SingleAngle, 3DoubleAngles, 3SingleAngles, BoxScale, Folding, DSquare, NoVariable, Folding16, 6SingleAngles, DRecipro, 2Doubles, DSqrReci, 2Singles, 4Singles, 3ScalesAngles, ScalesRot, 2Integer, SReci2, DReci2), and a line of another kind is ignored. At most 16 option values are kept; a 3SingleAngles takes three of them and a 6SingleAngles six.
• The defaults are DEscale 1, ADEscale 1, SIpower 0, RStop 16, DEoption 0.
• The SSE flags make the program refuse the formula on a processor without that instruction set.
• .Version must be 2 or more and no more than the program’s own formula number (9 in the source on GitHub); a lower number is “an old one”, a higher one “designed for a more actual version”.
• Constants are read from [CONSTANTS] as 8-byte slots: Double, Single and Int64 lines (in an older style a line carries a name: .Double name = 1).
• The code is read from [CODE] two digits a byte, up to 4,095 bytes, and must be more than 10 bytes. The source also knows a [SOURCE] section with Delphi source text that it compiles; none of the files has one.
• The text after [END] is the description, up to about 100 lines.
• The formula’s name is its file name without .m3f (up to 31 characters); the file does not name it. That is the name a parameter file stores.
• .DEoption is the distance estimate type (iDEoption): the source treats 20 as the dIFS type (and 20 to 22 as dIFS options), 4 to 6 as the four-dimensional analytic types, and ignores a negative one when it works out a hybrid’s estimate, which is why add-ons have -1.

Variations

All of them start with the line [OPTIONS]. The variation is the number in the .Version line, which is the first option line in all but a few files (they put .DEoption before it). The explorer tries the parser for each version in turn. The counts below are of the 714 files on this machine (412 different ones, as the Knowledge and Lewpen folders hold copies of each other).

00000000  5B 4F 50 54 49 4F 4E 53 5D 0D 0A 2E 56 65 72 73
00000010  69 6F 6E 20 3D 20 32 0D 0A 2E 44 45 6F 70 74 69   [OPTIONS]  .Version = 2  .DEopti…

A formula with any other number is read as the same layout and shown under “other version”; the numbers 1 and 7 are missing from the files seen here, and nothing is known of what they would be.

Not described

What this page and the explorer leave out or only infer, for every version of the format.

• Reference: what each .Version number changes is not known. The program’s source only accepts 2 to 9; the differences listed here (instruction sets, option kinds, DE options) are what the 714 files show, not a specification. The numbers 1 and 7 occur in no file.
• Reference: of the .DEoption values, only -1 (add-on), 4 to 6 (four-dimensional analytic types) and 20 and above (dIFS) have a meaning in the source; 0, 1, 2, 11 and 21 are seen in files but their meaning is not described.
• Reference: the calling convention of the machine code (which registers hold x, y, z and w, what the option pointer points at) is read off the disassembly of sample files, not from documentation, and is not described for every formula. What each formula computes is described only where its own description says so.
• Reference: the [SOURCE] section of the program’s source, the .SSSE3 and .SSE4 flags and constants of the kinds Integer and Single are not in any of the files, so they are described from the loader only.
• Viewer: the machine code is shown as a linear disassembly, an instruction decoded where the one before ends. It does not follow jumps, tell code from data, or show the constants the code addresses beside it; the options are not linked to the code that reads them.
• Viewer: nothing is run or checked for being valid or safe; the description is shown as text (Windows-1252), and a version that is not 2 to 6 or 8 is shown as the same layout under “other version”.

Links