.M3F File Format

Introduction

A version 4 formula is a Mandelbulb 3D formula file whose first option line is .Version = 4. Twenty-eight of the 714 files examined have it (twenty different files). They include the _reciprocalX3, _reciprocalY3 and _reciprocalZ3 add-ons (and their b versions), and the Amazing Box variants ABoxVaryScale, ABoxVS_icen1, ABoxPlatinum, ATetraVS and Amazing Surf. Every one of the 28 has a .DEoption line.

The file is Windows text, lines ending in CR LF, and the code is 32-bit x87 machine code written as hexadecimal digits.

Layout

Option lines

No version 4 file has an .SSE2 or .SSE3 flag, a 2Doubles or a Single option.

Machine code

The code is a procedure that starts 55 8B EC (push ebp; mov ebp, esp), loads [ebp+8] and takes the pointer at offset 0x30 for its option values, which it reads at negative offsets ([esi - 0x10]). It reaches x, y and z through eax, edx and ecx. Most files end with C2 08 00 (ret 8). This is read off the disassembly of the sample files.

A worked example

_reciprocalX3.m3f is 438 bytes. Its description gives the formula as x' = sign(x)(1/Lim - 1/(abs(x) + Lim)).

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 34 0D 0A 2E 44 45 6F 70 74 69   ion = 4  .DEopti
00000020  6F 6E 20 3D 20 2D 31 0D 0A 2E 44 52 65 63 69 32   on = -1  .DReci2
00000030  20 4C 69 6D 69 74 65 72 20 3D 20 30 2E 35 0D 0A    Limiter = 0.5  
00000040  5B 43 4F 44 45 5D 0D 0A 35 35 38 42 45 43 35 36   [CODE]  558BEC56

The code is 44 bytes: 55 8B EC 56 52 DD 00 8B 75 08 8A 50 07 8B 76 30 D9 E1 DC 46 F0 80 E2 80 D9 E8 DE F1 D9 E0 DC 46 E8 DD 18 30 50 07 5A 5E 5D C2 08 00. It loads x (fld qword ptr [eax]), takes abs, adds the limiter (fadd [esi-0x10]), saves the sign byte of x (mov dl,[eax+7]; and dl, 0x80), computes 1/… (fld1; fdivrp), negates and adds [esi-0x18], stores x and puts the sign back with xor [eax+7], dl. The option value at [esi-0x10] is the Limiter; [esi-0x18] is presumably its reciprocal, which the DReci2 kind keeps beside the value (the maths in the description needs 1/Lim).

Quirks

• A byte is never split across two hex lines; the last hex line is shorter.
• Two blank lines may follow [END] before Description:, as here.
• Text in the description may use Windows-1252 characters.

Not described

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

• Reference: what version 4 changes from version 3 is not known; the page describes what its 20 different files show.
• Reference: the .DEoption values 11 and 2 seen here have no stated meaning in the source; the meaning of the reciprocal-kind options (DReci2) is inferred from the code and description of one formula; the code’s register use is read off sample disassemblies.
• 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.

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