Id 1.2 will remove all integer math code

[LegalizeAdulthood]

In email discussions, @PaulTheLionHeart and I have been discussing when to kill off the integer math fractal code. There is even a branch in the official fractint subversion repository, called fractint-float, where all the integer math fractal code has been removed.

The integer math code was useful when a CPU didn't have builtin hardware floating-point support and buying a floating-point math corprocessor was potentially expensive or your motherboard might not have even supported it. Now, every desktop and mobile CPU has plenty of hardware floating-point performance and the integer math code is simply a maintenance burden.

After version 1.1 releases at the end of January 2025, I will start on a quick 1.2 release that does nothing but remove the integer math fractal code. This removal has always been "on the plan" for some time, but it will simplify the steps going forward to wxWidgets in the 2.0 release and beyond.

[PaulTheLionHeart]

I wonder if we can replace the integer arithmetic with double double or quad double arithmetic as all the structures are in place. It may save time later if we want to add these arithmetic types.

[LegalizeAdulthood]

To handle DD or QD (as well as GMP style arbitrary precision) math types, I think first the existing hard-coded formulas and algorithms need to be parameterized by data type as template functions. Then instantiating them for DD, QD or GMP arbitrary precision types is just another instantiation of the template. This will bring full datatype support without duplicating code, which is always a source of bugs.

The best first step in that direction is to eliminate all the integer math stuff because it has so much manual fiddling of the fractional shifting that the code diverges too much from the floating-point versions.

So we're heading in that direction (DD, QD, GMP) for every escape-time fractal type, but we're not there yet :)

[LegalizeAdulthood]

I'm making good progress here already:

• Version support added in the GIF extension block to distinguish Id versions from legacy FRACTINT versions
• reset parameter extended to reset=major/minor/patch/tweak for parameter files created by Id; reset=<num> treated as a legacy version number
• Some parameter adjustment code restored when reading legacy version GIF files (although I think this is an extremely unlikely event as we're talking about reading GIF files from 25+ years ago)
• FractalType field added to FractalSpecific structure and the array indices are decoupled from the FractalType enum value

[PaulTheLionHeart]

That's great. Sometime, when we move to true colour, it may be worth considering PNG that handles true colour. Id can still read GIF but only write PNG. This is what I do in ManpWIN. I use the tEXt chunk for the p[arameters so it can be read by humans. There's no need to compress it.

[LegalizeAdulthood]

Adding PNG support isn't that difficult in terms of the file I/O, but I'd like to disentangle the encoder/decoder code from the timer callback stuff used currently. When GIF encoding/decoding was expensive, you wanted to know how long it would take as you watched the progress bar crawl down the side of the screen.

[PaulTheLionHeart]

Great, We can leave it until we migrate to true colour.

[LegalizeAdulthood]

I got my local tree working with all the integer types removed from the FractalSpecific array and basic migration of integer types to their floating-point equivalent types on image read.

....and it's a good thing I added all those image compare tests!

A handful of fractal types render differently now... and I don't mean just a little different because of integer vs. floating-point precision, I mean wildly differently like 45% of the pixels don't match. Viewing the test image and manually comparing it to the reference makes it blatantly obvious that something is very different. So, a good amount of progress made, but I'll have to come back to this after I get the hotfix out for 1.1.1.

Yay tests!

[PaulTheLionHeart]

Maybe this explains the differences we find in a number of FOTDs. There may have been a bug in the integer aritmetic versions.

[LegalizeAdulthood]

No, I think those are differences between the assembly code formula engine and the C code formula engine.

One of the test images that fails is:

gold-manzpower-4-perturb.gif

...which doesn't use formulas.

When I look at the rendered test image, it's clearly shifted to the right compared to the gold image.

I think the problem is due to some improper initialization for the specific fractal types; most fractal types rendered identical.

[LegalizeAdulthood]

The broken test images turned out to be due to the integer types and the floating-point types not specifying the same parameters and starting region. Once the floating-point types were made consistent with the integer types, the rendered images came out the same.

[PaulTheLionHeart]

Well done Richard. Those kinds of bugs can be frustrating.

[LegalizeAdulthood]

I've removed all the integer math code now and added tests using GIF images saved from DOS FRACTINT to verify that old GIF images with the integer types saved in them are properly migrated to their corresponding floating-point types. All of those changes have been pushed to the master branch. Removing this code was made significantly easier by ReSharper for C++ and a few tricks I employed along the way to get the tool to help me remove the relevant code.

I'm going to let the code simmer until the close date of the 1.2 milestone so that there is more time to validate the changes with manual testing. While every effort was made to ensure that the changes were made safely, most of the code in question isn't under detailed tests, although the image compare tests cover most of the fractal types.

In the meantime, in addition to manual testing, I'm going to continue working on the wx branch to get version 2.0 moving ASAP.

[LegalizeAdulthood]

I'd like to keep 1.2 isolated to just removal of the integer types. The release date is only a few weeks away, so it's not much of a delay. The master branch will stay stable until 1.2 is released unless more changes are needed to correct mistakes in removing the integer code. I do have one issue slated for 1.2 that is a documentation change only.

So I'm thinking the perturbation improvements should come in the next release, which I'm hoping will be the wxWidgets port to 2.0.

I'm thinking we could collaborate on the perturbation changes over the next few weeks until 1.2 is released an sort out the remaining issues from where you are now.

[PaulTheLionHeart]

This sounds really good. I am happy to wait until wxWidgets are added. Then we will have a great program. I feel like Id 2.0 is the real beginning of what we are trying to achieve. I'm also thankful for support with perturbation.

[LegalizeAdulthood]

Yes, Id 1.x still has very much the look and feel of a DOS program.... because it is :)

As I was removing all the integer stuff, it was pleasing to see the code getting simpler.

[PaulTheLionHeart]

That's great as I still struggle to understand a large amount of Id code.

[LegalizeAdulthood]

Well done Richard. Is the updated perturbation a candidate for Id 1.2? I'm getting close to fixing many of the issues.

Thinking about this a little more... we still have a couple weeks, so if we can get your current changes debugged and have perturbation working with all the passes algorithms, then what the heck, we might as well include it. :)

[LegalizeAdulthood]

I've updated the documentation files to describe the changes in this release and that completes the last remaining issues for the 1.2 milestone.

[PaulTheLionHeart]

What about solid_guessing, boundary_tracing and symmetry? Will they be ready in time?

[LegalizeAdulthood]

I think that's what we need to get working in the next few weeks; it feels doable to me.

[PaulTheLionHeart]

That's great. I look forward to where we will get to in such a short time. Thanks.

[LegalizeAdulthood]

One of the greatest strengths of Id has always been the extensive help documentation, so it's important to modernize this asset as well as the code. The HTML version of the documentation has been greatly improved for 1.2.

All the documentation for the fractal types has been updated to use AsciiMath markup around the various bits of formulas and math (or 'maths' as Brits say) that are rendered into the AsciiDoc markup to produce the HTML help with asciidoctor. This only affects the HTML documentation; the 'printed manual' and the in-program help still use the ASCII style rendition of formulas. The documentation linked from the repository uses the HTML help for the current version. The installer includes the HTML help along with an installed shortcut to the local HTML file. At some point the ASCII rendered in-program help will be replaced with the HTML help. We'll probably limp along with hc, the help compiler, for a while before that is dropped entirely and the AsciiDoc becomes the one source of truth for all the help.

Along the way I fixed #259, a bug in the help compiler that was preventing proper AsciiDoc markup from being emitted.

Going forward we'll be generating a PDF of the manual (see #262) from the AsciiDoc markup for those who like hardcopy documentation instead of the ASCII text file formatted for printing.

[LegalizeAdulthood]

1.2 has been released, many thanks to @PaulTheLionHeart for helping out!