Thomas de Groot <tho### [at] degrootorg> wrote:
> I am currently browsing through the include files to see if I can give a
> meaningful contribution to their upgrading to 3.7+ standard. Over time,
> some have been added to or partly upgraded, some are in am almost
> pristine state going back to version 3.1.

Thanks, Thomas.
I still have a few include files from Friedrich Lohmueller that I was working
through to tighten up the code and try to explain what was going on.


> The fundamental question is: What do we want?

Short answer: you really can't ever tell.
You may want to somehow include all three.
CloudySky1
CloudySky2
CloudySky3

Or maybe put all 3 versions in a macro with a version argument, and use #switch
to pick which one gets used.


Very long version:


I try to keep in mind that these files are accessed for usage, reference, and
learning.
So, the way I (try to) approach my stuff, is a chaotic mix of the following:

1. The simplest bare-bones example whose text can be used in the copy-paste
mechanism of the Insert Menu.
Because Whether I'm tired or forgetful, or whatever - I approach this part from
a New User perspective, and just want to plug in some working code from the GUI.

The only "extra" here, is that for something like a macro, I like to write a
working line of code or two to illustrate its actual usage in a scene.

2. Since these might be used as a reference to how certain features work, or as
the basis for the development of new SDL, or just as a historical record of
POV-Ray development, I like to get rid of "magic numbers", give things
meaningful identifiers, and perhaps restructure the formulas and code a bit so
that it's neat, clean, and easy to follow.
Author, date, version number, revision comments, etc.
This might comprise a completely separate "meta-version" of the code, which has
#debug statements enabled by #if_def (Verbose), etc.

One thing I've toyed with but haven't really fleshed out and used extensively,
if to come up with a naming scheme for almost everything, so that 400 lines into
some complicated scene code, I can get a clue about what's going on, and jump a
few steps ahead in the debugging process.
f_Identifier - function
v_Identifier - vector quantity
s_Identifier - scalar quantity
C_Identifier - color
P_Identifier - Pigment
T_Identifier - Texture
L_Identifier - a loop variable: #for (L_Identifier, 0, 10)

If Verbose is defined (boolean), I may send some comments to the debug stream
showing that a macro has indeed been invoked, and has exited.  That's just
because a scene with a large number of nested things can get pretty crazy,
trying to figure out where things went wrong.  Looking at the debug stream, I
can count the number of opening and closing statements and see where things went
off the rails.

For complicated formulas, or ones that probably won't have obvious meaning, a
few comments on what it does, how it's composed, what the assumed inputs and
outputs are, and perhaps a reference to the origin of the formula can go a long
way.
// based on code / formula for [whatever] - POV-Ray, Graphics Gems, ShaderToy,
website URL, math textbook, etc.
// Takes 2 vectors and uses the point-slope formula for a line to....
// divide both sides by x and cancel out [term] ....


On rare occasion, just for kicks, I've sent the stepwise solution to the worked
problem to the debug stream.

Along those lines, you might not worry so much about which fish to give the
end-user, and instead include a texture-generating macro that teaches someone
how a nice sky texture gets generated from first principles.
Links to the wiki for various features ought to help people quickly grasp what's
going on and possibly avoid the rehashing of the usual "how do I...", and even
if they do ask, anyone can just post a quick and simple "Just look at
m_ExampleMacro () in skies.inc - it _shows_ you how to do _everything_ ...

If you use "Step" as a macro argument, then you could progressively step through
the code line-by-line by doing something like
#if (Step > 0)
#declare P_SkyBasis = pigment {bozo};
#end
#if (Step > 1)
#declare P_StretchedSky = pigment {P_SkyBasis scale <10, 1, 50>}
#end

etc.
Every increment to step executes ALL of the previous steps.
Of course, you could use clock as well...

Post a reply to this message