.M3F File Format

Introduction

A version 2 formula is a Mandelbulb 3D formula file whose first option line is .Version = 2. It is the commonest kind: 417 of the 714 files examined. More than half are add-ons whose name starts with an underscore and whose .DEoption is -1 (237 files); the rest are ordinary formulas, with .DEoption 2 (42 files) or 4 (26 files) or none. They are small: the code of an add-on such as _AbsX is 33 bytes.

The file is Windows text, lines ending in CR LF, and the code is 32-bit x86 written as hexadecimal digits. Mandelbulb 3D loads the code into memory and calls it once for every iteration of every point it tests.

Layout

A file is a series of sections, each started by a line in square brackets. Lines end with CR LF; text is Windows-1252 (the sample files hold a few accented letters in the description).

Option lines

Every line starts with a dot. There are two forms. A setting is read by the program by name:

An option is a value the user can change in the program, written .<kind> <label> = <default>. The kind says how the value is stored and shown. Kinds seen in version 2 files:

The value is written with a decimal point, may start with + or . (+.3183, .5) and may use an exponent (6.1e-5). The program keeps a value for each option in the parameter files; the code reads them from memory at negative offsets from a base register (see Machine code).

Machine code

The code is the body of a procedure with the program’s own calling convention. In the version 2 files the code starts 55 8B EC (push ebp; mov ebp, esp), loads the pointer passed in [ebp+8], takes from it at offset 0x30 a pointer to the block of option values, and ends with C2 08 00 (ret 8). The three numbers being iterated are reached through the registers eax, edx and ecx, which point at x, y and z; floating point is x87 (D9 and DD opcodes). The option values are read as [esi - 0x10] and the like.

This was read off the disassembly of the sample files and is not from the program’s source; the explorer’s Machine code table shows each instruction beside the hexadecimal digits it comes from.

A worked example

_AbsX.m3f is 293 bytes. It computes x' = abs(x + fixX) - fixX.

00000000  5B 4F 50 54 49 4F 4E 53 5D 0D 0A 2E 56 65 72 73   [OPTIONS]  .Vers
00000010  69 6F 6E 20 3D 20 32 0D 0A 2E 44 45 6F 70 74 69   ion = 2  .DEopti
00000020  6F 6E 20 3D 20 2D 31 0D 0A 2E 44 6F 75 62 6C 65   on = -1  .Double
00000030  20 66 69 78 58 20 3D 20 30 2E 30 0D 0A 0D 0A 5B    fixX = 0.0    [
00000040  43 4F 44 45 5D 0D 0A 35 35 38 42 45 43 35 36 38   CODE]  558BEC568
00000050  42 37 35 30 38 38 42 37 36 33 30 44 44 30 30 44   B75088B7630DD00D
00000060  44 34 36 46 30 44 45 43 31 44 39 45 31 44 44 34   D46F0DEC1D9E1DD4
00000070  36 46 30 44 39 45 30 44 45 43 31 44 44 31 38 35   6F0D9E0DEC1DD185
00000080  45 35 44 43 32 30 38 0D 0A 30 30 0D 0A 5B 45 4E   E5DC208  00  [EN
00000090  44 5D 0D 0A 0D 0A 44 65 73 63 72 69 70 74 69 6F   D]    Descriptio

The code’s 33 bytes are the 66 digits 558BEC568B75088B7630DD00DD46F0DEC1D9E1DD46F0D9E0DEC1DD185E5DC20800; the first line holds 64 of them, and the second line holds only 00 (the last byte of ret 8). Read as instructions:

Quirks

• The hex lines are 64 digits, but a byte is never split across a line: a line holds an even number of digits.
• The explorer reads the line breaks as CR LF; a file with bare LF is read as well.
• An option with no = is a flag (.SSE2). An option kind the program does not know is kept in the file; the explorer shows it as an option of a kind not seen.
• The .Version line is first in all but a few files of other versions; in version 2 it is always the first.
• The description may hold bytes above 0x7F that are not UTF-8 (the explorer reads them as Windows-1252).

Not described

What this page and the explorer leave out or only infer for version 2 files.

• Reference: what .Version = 2 means beyond the files is not known; it is the commonest number (417 files) and the lowest the program accepts, and nothing says what the later numbers added.
• Reference: the .DEoption values 2 and 4 seen here have no stated meaning in the source (only -1 for add-ons is described), and the registers and option offsets of the code are read off the disassembly of sample files, not from documentation.
• Reference: the maths of each formula is not described except where the file’s own description gives it.
• Viewer: the machine code is a linear disassembly (no jump following, no data/code separation, constants not shown beside the code); options are not linked to the code that reads them; the description is plain Windows-1252 text.

Variants

• Version 2 – the commonest: x87 code with a push ebp prologue, many add-ons
• Version 3 – twelve files, among them David Makin’s formulas, with SSE2 and SSE3 flags
• Version 4 – twenty-eight files, the reciprocal add-ons and Amazing Box variants
• Version 5 – sixty-one files, mostly four-dimensional formulas
• Version 6 – one hundred and ninety files, mostly the dIFS formulas
• Version 8 – six files, the newest number seen

Links