Warning: non-newbies will face palm.  Three times.

In my earliest POVing days, I had scene files on two different 
computers, transporting them back and forth via floppy disks.  Nowadays, 
both sets of files are on one computer, in separate directory trees. 
Over time, I have been gradually syncing the files and merging them into 
one tree.

The biggest challenges have been two #include files.  One of them is my 
3rd generation prefab render rig, and the other is a set of common 
definitions that I used to use a lot.  These two files are not a concern 
for me nowadays because I no longer use them for new scenes; my render 
rig is in its 4th generation, and most of the common definitions have 
found their way into the Object Collection.  But over the years, I had 
made scene-breaking changes to these files, and for the first few months 
(face palm warning) I did not document these changes.

This means that, as I merge old scene files that #include these two 
files, I need to re-render them to see whether they still work, and with 
which #include file versions.  Usually, it's just a matter of setting 
version switches, but lately, I've been merging some of my oldest 
scenes, deep into undocumented updates territory.  I am running into 
multiple levels of intractable incompatibilities.

But this latest snag--it's not even a matter of documentation, as I did 
comment the reason for the change.  I did not provide for backward 
compatibility, because I figured the change was transparent.  I 
originally defined functions Sqr(), Cubed(), and Sign().[1]  Then (two 
face palms incoming) I decided these functions were too slow, so I 
converted them to macros!

The POV-Ray 3.5 reference manual made clear that calling external macros 
incurs overhead.  Based on the date stamps of the scene files that call 
Sqr(), I had already been using POV-Ray for nearly 3 months, plenty of 
time to have learned this.  Where was my head?

And in isosurfaces?  The macros would resolve at parse time, and the 
render halt complaining about an undeclared identifier.  What possessed 
me to write general-purpose macros for use in functions?

All I can think of today is that at the time I figured these functions 
were simple enough that resolving them at parse time would not cause 
complications.  The macro overhead would be irrelevant during the render 
phase.  I must have gotten lucky with the first few scenes I rendered 
with the change.  Either that or I had been so frustrated with the 
slowness of previous isosurface renders that I never bothered 
re-rendering them after changing the #include file.  Anyhow, I pretty 
quickly stopped using these macros in new scenes.  But as I re-render 
the old scenes, the problem surfaces.

In the intervening years, I have decided that if a procedure can be 
defined as either a macro or a function, it is better to define it as a 
function.  One just has to keep in mind POV-Ray's scope leakage 
problems[2] when choosing names:

   - Once a macro is defined, its name cannot be reused as a global or
     local identifier--though it can be reused as a macro formal
     parameter.
   - Once a function is defined, its name cannot be reused as a global
     or local identifier--though it can be reused as a macro formal
     parameter.
   - Once *any* identifier is declared, it cannot be reused as a macro
     name.
   - Once *any* identifier is declared, it cannot be reused as a
     function name.
   - Once *any* identifier is declared, it cannot be reused as a
     function formal parameter.  (If you were unlucky, math.inc 3.5
     would bomb out for this very reason.  Precautions were taken
     starting with math.inc 3.6; for an example, you can take a look
     at function adj_range2().)

Also, document everything!

________________________
[1] I hadn't yet discovered f_sqr() and sgn() from math.inc, but they 
are tangential to the matter anyway.  Fortunately, the existence of 
these functions eases the conversion of the affected scenes.
[2] If you have formal computer science education, you are mortified by 
these restrictions, wondering how people smart enough to create POV-Ray 
could have allowed such boneheaded violations of modular practice.  I am 
assured that the current development team is aware of such problems. 
Yes, I will keep complaining about the scope leakage until it is fixed.

Post a reply to this message