This is a third follow-up to the thread "povray standard include files" to 
discuss development standards for a proposed area on povray.org for storage 
and distribution of a collection of objects and other files, contributed by 
the POV-Ray community. A closely associated issue raised in the original 
thread was how to maintain diversity in our scenes. The concern expressed 
was that, if many people use the same objects, the scenes that our community 
produces could become pretty repetitive.

As Sabrina has mentioned, there are certain standard ways of doing things 
that can help us to construct #include files that will work together and 
also minimise compatibility issues with future versions of POV-Ray. For 
example, using #local in include files wherever you don't need to expose 
them externally. Also starting variable names, macro names etc. that are 
exposed with an upper case letter to avoid potential conflicts with future 
POV-Ray keywords.

I think Sabrina's idea of using a unique prefix for names is a good one and 
I've used this in the past, for example, all POV-Stairs variables exposed 
externally start with SC (for StairCase). Interestingly I started using PS 
but found that someone elses include file used PS. Nevertheless, because it 
was standard I could do a case sensitive global change and was able to 
quickly change all my PS's to SC's. The lesson here is that using a standard 
makes life easier than not using a standard, even if the detail needs to 
change.

I don't think I'd agree with the idea to take naming standards to the level 
of requiring macros to contain the word 'Macro' in the name. I suspect that 
going back and retrospectively adjusting some of my own #include files would 
be cumbersome. For example, there are lots of macros in the various 
POV-Person #include files and they're mentioned all over the place in the 
documentation. Anything that needed doing to the names that couldn't be done 
with a global change would absorb lots of time (although Hungarian notation 
might work).

Florian raised the point that having a standard for sizes and names can make 
it less likely that someone put's his objects/textures/whatever in the 
collection, because it's too much hassle. Maybe a solution to this is that 
we document a standard, but don't insist people use it. We could have an 
indicator on the web site to show whether a particular submission adheres to 
the standard. This would also enable older and non-compliant files to still 
be published, but users would be forewarned about maybe having to sort out 
conflicts. From time to time we could drive campaigns to help standardise 
the most popular and well-used materials.

On the subject of Object Diversity I think we could probably come up with 
some best practices that would help people to write #include files in a 
parametrised way that permits people using the file to readily adjust as 
much as possible. For example, using #ifdef() before #declare inside the 
#include file helps someone to override default settings within their scene 
file. Rather than writing that sort of thing into our standards, I would 
propose that we assemble (or reference if some already exist) a few 
tutorials that illustrate how to build include files that enable a diverse 
range of objects to be generated.

Regards,
Chris B.

Post a reply to this message

"Chris B" <c_b### [at] btconnectcomnospam> wrote:
> A closely associated issue raised in the original
> thread was how to maintain diversity in our scenes. The concern expressed
> was that, if many people use the same objects, the scenes that our community
> produces could become pretty repetitive.

My proposal would be to have as few actual #declares as possible and instead
rely on macros to assemble components together.  This way, we'd get highly
parametrized objects/pigments/finishes/normals/color_maps etc.  It could
also benefit by encapsulation inside the macro, so that less naming
conflicts would happen.  Macros also allow far more randomness because
objects are created each time, and each time you could feed a different
"randomness" parameter or global variable to the macro...

Textures separate from shapes as well, after all, i could always want a
chrome potato instead of a boring everyday one. :)

> For example, using #local in include files wherever you don't need to expose
> them externally.

i just wish #local would also be local to macros.  oh well...

> Nevertheless, because it
> was standard I could do a case sensitive global change and was able to
> quickly change all my PS's to SC's.

in fact, this could be handled by a script server-side, by attributing
string IDs to contributions and prefixing #declares and macros
automatically.  Of course, caution should be made for not letting 2 letter
prefixes suddenly become 8-letter ones and very java like...

Still, i take it none of you want deeply nested well-organized directory
structures, ain't it true?  I really don't agree with just IDs and prefixes
and think a well-organized hierarchical directory structure for includes
should pay off in the long run.

> I don't think I'd agree with the idea to take naming standards to the level
> of requiring macros to contain the word 'Macro' in the name.

in the case of macros specifically, it seems a tradition in the povray
community to use make_foo patterns.  I like it. :)

> Florian raised the point that having a standard for sizes and names can make
> it less likely that someone put's his objects/textures/whatever in the
> collection, because it's too much hassle. Maybe a solution to this is that
> we document a standard, but don't insist people use it. We could have an
> indicator on the web site to show whether a particular submission adheres to
> the standard. This would also enable older and non-compliant files to still
> be published, but users would be forewarned about maybe having to sort out
> conflicts. From time to time we could drive campaigns to help standardise
> the most popular and well-used materials.

this all seems more of a hassle than to standardize it before submitting in
the first place. :)

Standard metrics-compliant include files could merely declare a known and
standardized flag variable to state they're compliant.

> On the subject of Object Diversity I think we could probably come up with
> some best practices that would help people to write #include files in a
> parametrised way that permits people using the file to readily adjust as
> much as possible.

heh.  I just realized indeed many people in the povray community use include
files as some sort of glorified macro, #declares as parameters and several
#includes of the same file if several "instances" of the same object is
needed.  And it really makes sense, since macros don't really come with
local scope... although kludgy...

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:
> Still, i take it none of you want deeply nested well-organized directory
> structures, ain't it true?  I really don't agree with just IDs and prefixes
> and think a well-organized hierarchical directory structure for includes
> should pay off in the long run.

I'm still going on the assumption that we're talking about a downloadable
..zip file containing an entire library of whatnots & widgits, so being able
to tell POV-Ray to make the whole library accessable would be really handy.
To do that, you could add all the directories and sub-directories of the
library to the master .ini file hoping that you don't exceed POV-Ray's
limit on that... (Wasn't it something like 22 directories max?  I don't
have time to check atm.) Does anybody know the reason for the limit?  Since
Chris Cason mentioned it would be possible to make minor changes before 3.7
final, I wonder how hard it would be to give .ini files the option to tell
POV-Ray to search all sub-directories of a given directory.

Or, you could keep it to a single directory like the standard INCLUDE
directory that come's with POV-Ray (requiring added emphesis on naming
conventions).  I'm with you nemesis, I'd prefer at least some hierarchy.
For one thing, not all things come in single files.  A lot of use have
whole groups of related #includes that work together as their own little
package.

One place I think naming conventions come in especially handy is in
generated files...  For instance, I've got of macros which generate meshes,
and caching equivalent meshes of varying resolutions into files comes in
really handy.  But then comes the time when I want to back up of whatever
scene directory...  Those generated files can get big!  So, I always start
their file names with "Generated_" and then use a macro to put a comment at
the top of those files saying something like "This is a generated file and
can probably be deleted without too much harm.n"  If the generated files
have uniform file names, they're pretty quick to dispose of.

Charles

Post a reply to this message

nemesis wrote:
> heh.  I just realized indeed many people in the povray community use include
> files as some sort of glorified macro, #declares as parameters and several
> #includes of the same file if several "instances" of the same object is
> needed.  And it really makes sense, since macros don't really come with
> local scope... although kludgy...

It's a practice that's carried over from before POV-Ray had macros. 
Surprisingly, after ten years, people still do it...

...Chambers

Post a reply to this message

Chris B wrote:
> collection, because it's too much hassle. Maybe a solution to this is that 
> we document a standard, but don't insist people use it.

That's worse than having no standard, because then you have to check 
whether or not its standardized...

My opinion is, you make a standard, and stick to your guns.  People are 
still free to make their own files, and distribute them the 
old-fashioned way, so noone's really losing anything.  But for such a 
collection to be useful, standards are the way to go.

That being said, I think a few basic standards should be enough:
1) Each include file deals with only one object / texture / function / 
whatever (see #5 below for an exception).
2) No hard-coded sizes, everything must be parameterized.
3) All items should be generated by a macro for consistency.  If all 
you're doing is declaring a texture, still generate it by macro to match 
the consistency of everything else in the archive.
4) The name of said macro should be identical to the file name, but for 
heaven's sake, avoid Hungarian notation like the plague it is!
5) Where it makes sense, objects that can take advantage of 
randomization should come in two flavors: a basic one, with no 
randomization, and a random one (append the macro with _r if you must) 
which accepts as an additional argument, a random number stream.  This 
allows you to use your own random streams in the object creation process.

I think that's everything; at least, I can't think of anything else off 
the top of my head.

...Chambers

Post a reply to this message

Chris B wrote:

> As Sabrina has mentioned, there are certain standard ways of doing things 
> that can help us to construct #include files that will work together and 
> also minimise compatibility issues with future versions of POV-Ray. For 
> example, using #local in include files wherever you don't need to expose 
> them externally. Also starting variable names, macro names etc. that are 
> exposed with an upper case letter to avoid potential conflicts with future 
> POV-Ray keywords.

This is something that C/C++ programmers (and others as well) know: 
Don't use globals unless you really, really have to.

> I think Sabrina's idea of using a unique prefix for names is a good one and 
> I've used this in the past, for example, all POV-Stairs variables exposed 
> externally start with SC (for StairCase). Interestingly I started using PS 
> but found that someone elses include file used PS. Nevertheless, because it 
> was standard I could do a case sensitive global change and was able to 
> quickly change all my PS's to SC's. The lesson here is that using a standard 
> makes life easier than not using a standard, even if the detail needs to 
> change.

I already do this with my Subdivision Surface macros; everything starts 
with SSS or sss.

> Florian raised the point that having a standard for sizes and names can make 
> it less likely that someone put's his objects/textures/whatever in the 
> collection, because it's too much hassle. Maybe a solution to this is that 
> we document a standard, but don't insist people use it. We could have an 
> indicator on the web site to show whether a particular submission adheres to 
> the standard. This would also enable older and non-compliant files to still 
> be published, but users would be forewarned about maybe having to sort out 
> conflicts. From time to time we could drive campaigns to help standardise 
> the most popular and well-used materials.

Probably the biggest issue is that while many people around here use 1 
unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.

This is probably best addressed with a simple line at the start of the 
macro or scene file:

// -- uses centimeter scaling

> On the subject of Object Diversity I think we could probably come up with 
> some best practices that would help people to write #include files in a 
> parametrised way that permits people using the file to readily adjust as 
> much as possible. For example, using #ifdef() before #declare inside the 
> #include file helps someone to override default settings within their scene 
> file. Rather than writing that sort of thing into our standards, I would 
> propose that we assemble (or reference if some already exist) a few 
> tutorials that illustrate how to build include files that enable a diverse 
> range of objects to be generated.

Well, I use an #ifndef-#local-#end block, and it works fine.  My robot 
models have a default texture for different things; in fact, there is 
also a BotGender variable that specifies which of two defaults gets used.

And we can put code in the #ifndef-#local-#end block to detect if any of 
the defaults are changed, and print out "Use some imagination!" if none 
of them are changed :-)

Regards,
John

Post a reply to this message

John VanSickle <evi### [at] hotmailcom> wrote:

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the
> macro or scene file:
>
> // -- uses centimeter scaling

John, this is a good point.  However, in a rendered scene, all real-world
metrics are virtual and exist only in the mind of the author of the scene
or that of the viewer.

The only immutable metric in a rendered scene is the pixel.  For purely
technical purposes, what if the objects in publicly shared include files
are initially intended to be viewable in a scene with an 'orthographic
camera' with 'up' and 'right' vectors which correspond to a standardized
render window - say < 0, 480, 0> and < 640, 0, 0 > respectively?

That way, when the end user makes use of one of these objects, s/he can
calculate centimeter/pixel, meter/pixel, inch/pixel, etc. at some distance
from the camera they're using and scale the objects accordingly.  Of
course, if rendering an image with dimensions other than 640 x 480 ( my
usual preference ), then scaling would also have to reflect this as well.

Post a reply to this message

Ben Chambers <ben### [at] pacificwebguycom> wrote:

> That's worse than having no standard, because then you have to check
> whether or not its standardized...
>
> My opinion is, you make a standard, and stick to your guns.  People are
> still free to make their own files, and distribute them the
> old-fashioned way, so noone's really losing anything.  But for such a
> collection to be useful, standards are the way to go.


I think it all depends on what we're building here.  Something like a
professonal product containing the best of the best, or a community effort
containing some things that might not be as up-to-snuff as others.  If this
were a for-sale package, it'd be most professional to have everything be as
uniform as possible.  On the other hand, if it were up to me I'd like to
think of this thing to be a little more inclusive.  I think we'll be hard
pressed to find a single standard that won't turn most people away.  So,
I'd lean more towards guidelines, and tutorials on how to make #includes
"nice," kinda like what Chris B was talking about.

Charles

Post a reply to this message

John VanSickle <evi### [at] hotmailcom> wrote:

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the
> macro or scene file:
>
> // -- uses centimeter scaling

Heh, I use different measurement systems depending on what seems appropriete
for the thing I'm making.  I've said it in another post, but I do think that
scaling (& re-orienting) objects to fit your scene is just a fact of life.

BTW, I do also tend to use 1cm = 1 unit.

Post a reply to this message

From: Charles C
> Since Chris Cason mentioned it would be possible to make minor changes before 3.7
> final, I wonder how hard it would be to give .ini files the option to tell
> POV-Ray to search all sub-directories of a given directory."

I also have a suggestion, now that we're at it:  is it much hard to give
macros proper local scope for #local variables?  If it is, i guess the
practice of using the whole include file as a big macro will carry on...

From: Charles C
> I'd prefer at least some hierarchy.

Keywords are cool for searching, but not for organizing code.  Chris B
suggested having few main areas of interest as high-level branches and i'm
with him.  I'd also suggest each contributor having a short prefix
associated, so if, say, nem or chc both contribute cedar textures, it
should come like this:
textures/wood/nem_cedar.inc
textures/wood/chc_cedar.inc

or something.  The prefix would be automatically generated by a server-side
script taking into account the contributor's login or email or something.

From: Ben Chambers
>That's worse than having no standard, because then you have to check
> whether or not its standardized...
> My opinion is, you make a standard, and stick to your guns.  People are
> still free to make their own files, and distribute them the
> old-fashioned way, so noone's really losing anything.  But for such a
> collection to be useful, standards are the way to go."

I wholeheartdly agree.  People may or may not use the proposed standard and
may or may not benefit from it.  Nobody loses and people wanting a
standard gain a lot from it.

I proposed having a flag variable declared in each include file following
the standard, something like:

#declare USE_STD = yes;

Include files not following it simply don't have such flag and scenes
including the files can check if they follow the standard or not, like:

#include "landscapes/desert/nem_sand.inc"
#ifdef( USE_STD )
......
  #undef USE_STD // <- important!
#else
......
#end

From: Ben Chambers
> 1) Each include file deals with only one object / texture / function /
whatever (see #5 below for an exception).

fine by me

> 2) No hard-coded sizes, everything must be parameterized.

I don't think a default size would be bad, specially if we are able to
standardize the metrics.  Still, this is povray we're talking about, where
potatoes can be 50 meters tall and have chrome texture! :)

On the subject of sizes i believe it'd be good if people took their time to
scale contributed objects to fit either height or width to 1 unit, whatever
it is.  Because then, if i want it to have a 3 meter paper clip, i simply
scale it like "scale x*3" given the 1 unit fitting scheme used the width of
the object.

While we're at it, we live in a gravity centered world and generally objects
are not floating around, but lying into yet other objects.  I'd suggest
placing objects upon the origin, that is, the common bottom of the object
resting in y*0.  Like chairs resting on their feet or an egg lying to its
side.

> 3) All items should be generated by a macro for consistency.  If all
> you're doing is declaring a texture, still generate it by macro to match
> the consistency of everything else in the archive.

exactly!  and it brings composition and some randomness to the forefront.

> 4) The name of said macro should be identical to the file name, but for
> heaven's sake, avoid Hungarian notation like the plague it is!

for macros, the make_foo pattern is cool enough.  But personally, i
generally go for t_tex1, fn_fin1, p_pig1, n_nor1 and the likes for other
name patterns... I'd have to change to more closely match the CamelCase
style used by most povvers. :)

> 5) Where it makes sense, objects that can take advantage of
> randomization should come in two flavors: a basic one, with no
> randomization, and a random one (append the macro with _r if you must)
> which accepts as an additional argument, a random number stream.  This
> allows you to use your own random streams in the object creation process.

very good!

what about a level-of-detail parameter?  like, 1,2,3 for basic, medium,
complex?  or is it too much?  am i thinking too much ahead?

From: John VanSickle
> I already do this with my Subdivision Surface macros; everything starts
> with SSS or sss.

oh noes!  what about macros dealing with SubSurface Scattering?! ;)

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.

how about:
#declare UNIT = m;
or
#declare UNIT = cm;

as a way to explicitely declare your intentions for standard-compliant
scenes?

> And we can put code in the #ifndef-#local-#end block to detect if any of
> the defaults are changed, and print out "Use some imagination!" if none
> of them are changed :-)

lovely idea! :)

From: Randall Sawyer
> in a rendered scene, all real-world
> metrics are virtual and exist only in the mind of the author of the scene
> or that of the viewer.

yes, but nothing should prevent the author of putting some default in there
and people from using such default.

> what if the objects in publicly shared include files
> are initially intended to be viewable in a scene with an 'orthographic
> camera' with 'up' and 'right' vectors which correspond to a standardized
> render window - say < 0, 480, 0> and < 640, 0, 0 > respectively?

I think this is out of scope in the discussion, because we're talking about
metrics, size and placement standardization.  hopefully, lighting standards
could also come by...

yes, people viewing an object up close or very far away will have no notion
of metrics involved.  But the metrics standard should not be there for an
object alone, but to correctly relate it to other objects following such
standard.


From: Charles C
> I think we'll be hard
> pressed to find a single standard that won't turn most people away.

How something optional like the metrics standard could possibly turn people
away?  I say, let people wanting a metric standard to discuss metric
standard matters, let people wanting to address other issues address other
issues and let people just wanting to contribute something they created
contribute it without any metrics consideration whatsoever.

Post a reply to this message

Charles C wrote:
> Ben Chambers <ben### [at] pacificwebguycom> wrote:
> 
>> That's worse than having no standard, because then you have to check
>> whether or not its standardized...
>>
>> My opinion is, you make a standard, and stick to your guns.  People are
>> still free to make their own files, and distribute them the
>> old-fashioned way, so noone's really losing anything.  But for such a
>> collection to be useful, standards are the way to go.
> 
> 
> I think it all depends on what we're building here.  Something like a
> professonal product containing the best of the best, or a community effort
> containing some things that might not be as up-to-snuff as others.  If this
> were a for-sale package, it'd be most professional to have everything be as
> uniform as possible.  On the other hand, if it were up to me I'd like to
> think of this thing to be a little more inclusive.  I think we'll be hard
> pressed to find a single standard that won't turn most people away.  So,
> I'd lean more towards guidelines, and tutorials on how to make #includes
> "nice," kinda like what Chris B was talking about.
> 
> Charles

My reasoning for a well worded standard was because I was picturing this
becoming something like a STL for POV-Ray. When picking and choosing
certain includes, overlaps in variable and item names might not show up.
But we can't test every possible combination and they will show up
eventually.

This doesn't mean we can't have 'submitted includes' and 'standard
includes'. If this all falls under an open source license then we can
always fall back on the old 'if you want a non-standard include to work,
change it yourself.' Call them beta includes, even put them in a
separate zip file just to keep them apart. That way, anyone who wants to
put their code into this package can without editing anything if they do
not want to.

Post a reply to this message

Sabrina Kilian <ykg### [at] vtedu> wrote:
> My reasoning for a well worded standard was because I was picturing this
> becoming something like a STL for POV-Ray.

me too!  or boost! :)

> When picking and choosing
> certain includes, overlaps in variable and item names might not show up.
> But we can't test every possible combination and they will show up
> eventually.

some name mangling or aliases for simple namespace separation could be cool
if povray supported it...

Post a reply to this message

Hi all!

I just made an annotated include file which contains a single macro for
rendering a ruler using only '#local's - no '#declares'.  The tick-marks
and the numbers are in terms of its own metric.  The object could be
inserted into any scene.

Excerpt:

// Usage:
//  ruler( len[float], wid[float], dir[float[0, 1, 2, 3]],
font_name[string], font_scale[float], tick_interval[float[integer]],
tick_thickness[float], number_interval[float[integer]] )

Is there an appropriate place for me to upload the file on this site or
someone to whom I could e-mail it?

-Randall

Post a reply to this message

"Randall Sawyer" <sra### [at] yahoocom> wrote:
> Is there an appropriate place for me to upload the file on this site or
> someone to whom I could e-mail it?

right now you can upload it to the scene sources povray newsgroups.  If our
discussions in these threads lead anywhere, in the near future there will
be an area in the povray web site for people to upload include file
contributions...

Post a reply to this message

"Randall Sawyer" <sra### [at] yahoocom> wrote in message 
news:web.456c30f447def5ca8c37caaf0@news.povray.org...
> Hi all!
>
> I just made an annotated include file which contains a single macro for
> rendering a ruler using only '#local's - no '#declares'.  The tick-marks
> and the numbers are in terms of its own metric.  The object could be
> inserted into any scene.
>
> Excerpt:
>
> // Usage:
> //  ruler( len[float], wid[float], dir[float[0, 1, 2, 3]],
> font_name[string], font_scale[float], tick_interval[float[integer]],
> tick_thickness[float], number_interval[float[integer]] )
>
> Is there an appropriate place for me to upload the file on this site or
> someone to whom I could e-mail it?
>
> -Randall
>

Not yet, we're just trying to hammer out how we would the area under 
discussion to work.
I suspect it'll take a couple of weeks to let everyone have a say and arrive 
at a concensus, then we'll need to run it by the webmaster (Chris Cason) to 
see if what we've decided we'd like to do is viable on povray.org. Then, 
setup could take days or weeks, depending upon whether we need to create 
server-side scripts or anything sophisticated for submission, indexing, SDL 
validation etc.

There is the povray.binaries.scene-files newsgroup that you could use to 
publish your include file in the mean time.

Regards,
Chris B.

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:
>                                                                    If our
> discussions in these threads lead anywhere, in the near future there will
> be an area in the povray web site for people to upload include file
> contributions...

I know.  Don't you love the self-referential irony? "There's a hole in
the bucket..." ;)

Thank you, nemesis.  I'll post it there now.

-Randall

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:
> From: Charles C
> > I think we'll be hard
> > pressed to find a single standard that won't turn most people away.
>
> How something optional like the metrics standard could possibly turn people
> away?  I say, let people wanting a metric standard to discuss metric
> standard matters, let people wanting to address other issues address other
> issues and let people just wanting to contribute something they created
> contribute it without any metrics consideration whatsoever.

I was responding in the context of what I read Ben Chambers to be saying...
Ben, you tell me if this is right...  If I read it right, by "sticking to
our guns" I think Ben meant non-optional standards.  So, submissions which
do not follow x-standard should not be accepted at all, (Is that what you
meant Ben?) and that those who want to share something non-standard can do
so the old-fashioned way, (i.e. on the newsgroup or on their own web page).

I like standards, don't get me wrong.  I think in terms of making standards
for my own stuff too.  In a community thing where participation isn't
always easy to come by I think some flexibility is important.  Forcing a
few additions like adding flags is a lot easier than say, turning a dozen
related files into hundreds in order to qualify.

Charles

Post a reply to this message

Proposal to address the metrics issue using "Scene Ruler Objects"

I don't know how to cross-post.  I would have if I did know.  So, I'll be
brief instead:

Please read subject "Scene Ruler" in povray.binaries.scene-files, authored
by myself.  If the team decides that "scene rulers" are the way to go, then
I'll volunteer my services.

Also, I need some instruction on cross-posting.

Post a reply to this message

Charles C wrote:
> I was responding in the context of what I read Ben Chambers to be saying...
> Ben, you tell me if this is right...  If I read it right, by "sticking to
> our guns" I think Ben meant non-optional standards.  So, submissions which
> do not follow x-standard should not be accepted at all, (Is that what you
> meant Ben?) and that those who want to share something non-standard can do
> so the old-fashioned way, (i.e. on the newsgroup or on their own web page).


That's exactly what I meant.  For such a collection to be really useful, 
I believe that standards would be a necessity in order to facilitate 
usability.  Of course, if people don't want to conform to the standards, 
then you could still reference their files (or even host them on the 
server), but they should be kept separate from the main archive.

...Chambers

Post a reply to this message

[Chris B]
>> For example, using #local in include files wherever you don't need to expose
>> them externally.

Overall I am strongly in favor of some system whereby the only things exposed
from a specialized object or macro include file are those things the author
intends to expose, that is, by explicit declaration. C++ uses namespaces,
perl uses modules, other languages have their own ways; whatever, the point
is intelligent management of exposed symbols.

[nemesis]
> i just wish #local would also be local to macros.  oh well...

Recall I mentioned changes to SDL are possible. Not necessarily the above,
perhaps, but something that gives us the same effect. Basically if enough of
you think it's needed, tell me and we'll give it some thought. Some things
might not be possible with the current parser but we'll at least consider it.

-- Chris Cason

Post a reply to this message

Charles C wrote:
> pressed to find a single standard that won't turn most people away.  So,
> I'd lean more towards guidelines, and tutorials on how to make #includes
> "nice," kinda like what Chris B was talking about.

Here's an option:

Have two sections of the library: the 'standard', and the 'ad-hoc' one.
Everything goes into 'ad-hoc' to start with, until an administrator checks
it. If it meets the standard, it goes into the standard area. If it doesn't,
it either (a) stays in ad-hoc, (b) gets wrapped (see below) and moved into
standard, or (c) gets deleted.

Given a license that permits modifications or derivative works, if a macro is
good enough that it really should be in the standard area, but the author
didn't do it for some reason, a volunteer could encapsulate it within a
standards-compliant wrapper. Presuming support for some sort of private
namespace (or the equivalent thereof) is available, this would not always
require going though the entire file line by line.

Also I will mention that it is possible we could have a parser that reads SDL
and re-writes it according to a set of rules. I'm not about to volunteer to
do this but consider it as one possible means of handling issues that might
otherwise require run-time support within the distributed POV-Ray.

-- Chris

Post a reply to this message

FWIW I'd suggest some of you investigate how the Perl folks have handled
this, since they've gone through some of the same issues. While it is for
example possible to include a file into a perl program just like we do with
#include, they have another concept called 'modules' which covers some of the
issues here, plus some others that we haven't covered yet (e.g. modules can
be self-documenting). See:

  http://en.wikipedia.org/wiki/Perl_module.
  http://stein.cshl.org/genome_informatics/chervitz/perl-modules/

-- Chris

Post a reply to this message

"Charles C" <nomail@nomail> wrote:
> I think it all depends on what we're building here.  Something like a
> professonal product containing the best of the best, or a community effort
> containing some things that might not be as up-to-snuff as others.
> ...
> I'd lean more towards guidelines, and tutorials on how to make #includes
> "nice," kinda like what Chris B was talking about.

Chris Cason <del### [at] deletethistoopovrayorg> wrote:
> Have two sections of the library: the 'standard', and the 'ad-hoc' one.
> Everything goes into 'ad-hoc' to start with, until an administrator checks
> it. If it meets the standard, it goes into the standard area.

I like the direction in which this discussion is heading.

My personal preference is for #macro includes with a parameter each for size
or texture-density where appropriate.  I just got done rewriting my personal
includes, eliminating all #declares.  My headers now have two new lines:

// Manifest: #macro_1, #macro_2, ...
// Dependencies: "file_1.inc", "file_2.inc", ...

BTW: I'm more of a hands-on learner.  So, this exercise served to inform me
better in participating in this discussion.  It is not my intention to
promote my personal standard.  I share it only as an example.

I would still like to promote my "scene ruler" #macro-generated objects for
use by the 'ad-hoccers' who want to make their textures and such available
via #declares (assuming we do end up with an 'ad-hoc' area).

Also, I'd be happy to help with the tutorials.

-Randall

Post a reply to this message

Chris Cason <del### [at] deletethistoopovrayorg> wrote:
> FWIW I'd suggest some of you investigate how the Perl folks have handled
> this, since they've gone through some of the same issues. While it is for
> example possible to include a file into a perl program just like we do with
> #include, they have another concept called 'modules' which covers some of the
> issues here

Chris, i guess having proper lexical scoping helps a lot in getting true
module/package/unit/namespace...

The SDL right now just has global variables and per-file local variables.
Macro "local variables" seem like they are really just copied verbatim to
the location where the macro was followed, thus becoming local to the
callee file.  Macros are indeed a strange mix of C preprocessing macros and
procedures/functions...

Still, i guess its too costly for a change right now, so i think we'd better
deal with it for a while -- hey, C is still around! -- and see what we can
do with this limitation in mind.

>, plus some others that we haven't covered yet (e.g. modules can
> be self-documenting). See:

talking about it, code is the best document there is! :)

Post a reply to this message

Chris Cason wrote:

> [Chris B]
> 
>>>For example, using #local in include files wherever you don't need to expose
>>>them externally.
> 
> 
> Overall I am strongly in favor of some system whereby the only things exposed
> from a specialized object or macro include file are those things the author
> intends to expose, that is, by explicit declaration. C++ uses namespaces,
> perl uses modules, other languages have their own ways; whatever, the point
> is intelligent management of exposed symbols.
> 
> [nemesis]
> 
>>i just wish #local would also be local to macros.  oh well...
> 
> 
> Recall I mentioned changes to SDL are possible. Not necessarily the above,
> perhaps, but something that gives us the same effect. Basically if enough of
> you think it's needed, tell me and we'll give it some thought. Some things
> might not be possible with the current parser but we'll at least consider it.

Keeping it simple is a must.

Namespaces are probably the best way.  Ideas:

* #namespace LABEL creates the namespace LABEL if it doesn't already 
exist.  Whether new or not, namespace LABEL becomes the active namespace 
(the former namespace is saved on a stack).

* #namespace undef pops the current namespace off of the stack, and the 
former namespace becomes active.

* All #declare and #local statements affect the variable in the current 
namespace.  Other variables of the same name in other namespaces are not 
affected.

* #declared variables live from one invocation of the namespace to the 
next, but #labeled variables die when the namespace passes out of scope 
(end of macro, end of file, popped by #namepsace undef statement).

* The arguments of a macro are, within a macro, always in scope, 
regardless of the active namespace.

This way if I write a set of macros for simulating physics (called the 
Phony Physics Pholio), I can put

   #namespace Phony_Physics_Pholio

at the start of every macro, and thereby minimize conflicts with other 
macros sets by other authors.

Regards,
John

Post a reply to this message

John VanSickle wrote:

> Chris B wrote:
>
>> As Sabrina has mentioned, there are certain standard ways of doing 
>> things that can help us to construct #include files that will work 
>> together and also minimise compatibility issues with future versions 
>> of POV-Ray. For example, using #local in include files wherever you 
>> don't need to expose them externally. Also starting variable names, 
>> macro names etc. that are exposed with an upper case letter to avoid 
>> potential conflicts with future POV-Ray keywords.
>
>
> This is something that C/C++ programmers (and others as well) know: 
> Don't use globals unless you really, really have to.
>
>> I think Sabrina's idea of using a unique prefix for names is a good 
>> one and I've used this in the past, for example, all POV-Stairs 
>> variables exposed externally start with SC (for StairCase). 
>> Interestingly I started using PS but found that someone elses include 
>> file used PS. Nevertheless, because it was standard I could do a case 
>> sensitive global change and was able to quickly change all my PS's to 
>> SC's. The lesson here is that using a standard makes life easier than 
>> not using a standard, even if the detail needs to change.
>
>
> I already do this with my Subdivision Surface macros; everything 
> starts with SSS or sss.


Just some ideas from my personal coding standards...

I make all #declared items uppercase with a three-letter descriptive 
suffix; anything in an #include file gets a two- or three-letter prefix 
as well.  For example, a weathered oak texture in the hypothetical 
Outhouse.inc file would become OH_WEATHERED_OAK_TEX, a corncob would be 
called OH_CORNCOB_OBJ, and so on.  #local items are similar, but with 
upper- and lower-case:  BoardShapeObj, CorncobLength, and so on.  A 
#macro would be named something like macOH_MakeCorncob.

Any macro is preceded by a nice comment box, along the lines of...

////////////////////////////////////////////////////////////////////////
//  macOH_MakeCorncob--Creates a corncob to be placed in the corncob box
//    in the "Outhouse" project.
//
//  Parameters:
//    CorncobLength   = Float; length of corncob.
//    CorncobDiameter = Float; diameter of corncob.
//    TrimEnds        = Boolean; true  = ends of corncob are trimmed
//                               false = ends are untrimmed
//                               default = false
////////////////////////////////////////////////////////////////////////

...and gets an  "// end macOH_MakeCorncob" comment at the end.

(Yes, I know it's a silly example  ;)  I also tend to do things like 
naming a function to create a pink pigment PinkPigFun.  And so on.  I 
just can't help myself.)


>
>> Florian raised the point that having a standard for sizes and names 
>> can make it less likely that someone put's his 
>> objects/textures/whatever in the collection, because it's too much 
>> hassle. Maybe a solution to this is that we document a standard, but 
>> don't insist people use it. We could have an indicator on the web 
>> site to show whether a particular submission adheres to the standard. 
>> This would also enable older and non-compliant files to still be 
>> published, but users would be forewarned about maybe having to sort 
>> out conflicts. From time to time we could drive campaigns to help 
>> standardise the most popular and well-used materials.
>
>
> Probably the biggest issue is that while many people around here use 1 
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the 
> macro or scene file:
>
> // -- uses centimeter scaling
>

I wonder if some sort of generic unit conversion code might be posted on 
the site, to allow coders to use the units they find most appropriate, 
while simplifying end-users' ability to mix-and-match #include files...?


>> On the subject of Object Diversity I think we could probably come up 
>> with some best practices that would help people to write #include 
>> files in a parametrised way that permits people using the file to 
>> readily adjust as much as possible. For example, using #ifdef() 
>> before #declare inside the #include file helps someone to override 
>> default settings within their scene file. Rather than writing that 
>> sort of thing into our standards, I would propose that we assemble 
>> (or reference if some already exist) a few tutorials that illustrate 
>> how to build include files that enable a diverse range of objects to 
>> be generated.
>
>
> Well, I use an #ifndef-#local-#end block, and it works fine.  My robot 
> models have a default texture for different things; in fact, there is 
> also a BotGender variable that specifies which of two defaults gets used.
>
> And we can put code in the #ifndef-#local-#end block to detect if any 
> of the defaults are changed, and print out "Use some imagination!" if 
> none of them are changed :-)
>
> Regards,
> John


I use a block like...

#ifndef "_MyInclude"
  #include "MyInclude.inc"
  #declare _MyInclude = 1 ;
#end

...to avoid re-#including files in big projects with lots of #includes, 
and things like...

#ifndef "_TestMode"
  #declare _TestMode" = false ;
#end

...to set global parameters.  I imagine everybody has a collection of 
these code snippets to share.

--Sherry Shaw

-- 
#macro T(E,N)sphere{x,.4rotate z*E*60translate y*N pigment{wrinkles scale
.3}finish{ambient 1}}#end#local I=0;#while(I<5)T(I,1)T(1-I,-1)#local I=I+
1;#end camera{location-5*z}plane{z,37 pigment{granite color_map{[.7rgb 0]
[1rgb 1]}}finish{ambient 2}}//                                   TenMoons

Post a reply to this message

John VanSickle wrote:
> Namespaces are probably the best way.  Ideas:
> 
> * #namespace LABEL creates the namespace LABEL if it doesn't already 
> exist.  Whether new or not, namespace LABEL becomes the active namespace 
> (the former namespace is saved on a stack).
> 
> * #namespace undef pops the current namespace off of the stack, and the 
> former namespace becomes active.

Rather than that, why not just utilize
#namespace
with no arguments, to return to the global namespace?

> * All #declare and #local statements affect the variable in the current 
> namespace.  Other variables of the same name in other namespaces are not 
> affected.
> 
> * #declared variables live from one invocation of the namespace to the 
> next, but #labeled variables die when the namespace passes out of scope 
> (end of macro, end of file, popped by #namepsace undef statement).

You mean #local items, right?

I think namespaces are the perfect way to go, especially as the 
community using POV-Ray matures in their code-writing efforts.

...Chambers

Post a reply to this message

Sherry Shaw <tenmoonsPutAtCharacterHereaol-dot-com> wrote:
> John VanSickle wrote:

> > Probably the biggest issue is that while many people around here use 1
> > unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
> >
> > This is probably best addressed with a simple line at the start of the
> > macro or scene file:
> >
> > // -- uses centimeter scaling
> >
>
> I wonder if some sort of generic unit conversion code might be posted on
> the site, to allow coders to use the units they find most appropriate,
> while simplifying end-users' ability to mix-and-match #include files...?


If anybody's interested, Sherry your comment inspired me to make a little
macro which is expandable, but currently can convert any combination of
"mm", "cm", "m", "km", "in", "ft", "mi". I posted it here, and then as
usual found a minor error in a #debug statement & then re-posted.  I
wouldn't mind contributing this, realising it may need modification to fit
the standard we come up with. Any comments for improvement?

http://news.povray.org/povray.binaries.scene-files/thread/%3Cweb.4570c25ad5e52cf5e451c5d90%40news.povray.org%3E/

Charles

Post a reply to this message

Re: CSG fonts

I have an interest in developing and exchanging CSG fonts and CSG
font-formatting tools.  I have proposed adopting a standard for such
objects and macros in this thread:

http://news.povray.org/povray.binaries.scene-files/thread/%3Cweb.456ff0468ffcc40c7cac52a50%40news.povray.org%3E/

{ Please pardon my newbiisms and my footprints on a well-worn path, but
take seriously my proposal to adopt some sort of CSG font standard. }

In a nutshell:  I think it would be wise for default CSG font objects to
emulate default 'text{}'-generated objects.  And, I think it would be wise
to adopt a standard array structure to contain CSG fonts to allow for
portability among formatting tools.

-Randall

Post a reply to this message

Ben Chambers wrote:

> John VanSickle wrote:
> 
>> Namespaces are probably the best way.  Ideas:
>>
>> * #namespace LABEL creates the namespace LABEL if it doesn't already 
>> exist.  Whether new or not, namespace LABEL becomes the active 
>> namespace (the former namespace is saved on a stack).

By this stack thing I mean that the fact of being active is kept saved 
on a stack.

>> * #namespace undef pops the current namespace off of the stack, and 
>> the former namespace becomes active.
> 
> Rather than that, why not just utilize
> #namespace
> with no arguments, to return to the global namespace?

But there file or macro may return to code that had a different 
namespace active; returning to the global may mess that up.

To go to the global, there should probably be a keyword for it so that 
the scene coder gets a chance to know what he's doing.

>> * All #declare and #local statements affect the variable in the 
>> current namespace.  Other variables of the same name in other 
>> namespaces are not affected.
>>
>> * #declared variables live from one invocation of the namespace to the 
>> next, but #labeled variables die when the namespace passes out of 
>> scope (end of macro, end of file, popped by #namepsace undef statement).
> 
> You mean #local items, right?

Yeah, I meant #localed instead of #labeled.

> I think namespaces are the perfect way to go, especially as the 
> community using POV-Ray matures in their code-writing efforts.

I was trying to come up with something that is easy for the SDL user to 
understand (which means something far less complex that C++ namespaces), 
and which seems to be relatively simple to implement.

Regards,
John

Post a reply to this message

Sherry Shaw wrote:

> I wonder if some sort of generic unit conversion code might be posted on 
> the site, to allow coders to use the units they find most appropriate, 
> while simplifying end-users' ability to mix-and-match #include files...?

I tried to whip up a set of macros which allow a model designer to 
specify what units they're using, and another set which allows the scene 
designer to specify the units for the scene.  The two macros would work 
together to properly scale the object for the scene.

But making it sufficiently idiot-proof was too cumbersome, so I 
abandoned it to make time for playing Diablo.

Regards,
John

Post a reply to this message

"Randall Sawyer" <sra### [at] yahoocom> wrote:
> Re: CSG fonts

A brief update:
I released an improved (streamlined) version of my CSG Fonts standards
package.  To see it, please go to:

http://news.povray.org/povray.binaries.scene-files/thread/%3Cweb.456ff0468ffcc40c7cac52a50%40news.povray.org%3E/

Posting #6

Thank you,
-Randall

Post a reply to this message

Usage Protocol

Chris Cason wrote:
> Recall I mentioned changes to SDL are possible.

John VanSickle wrote:
> Keeping it simple is a must.
>
> Namespaces are probably the best way.  Ideas:
>
> * #namespace LABEL creates the namespace LABEL if it doesn't already
> exist.
.......

Would it be helpful to establish a way to view the 'usage text' of a macro
without having to load its entire include file into an editor?

One solution would be to require a

    #declare foo_usage = 'string literal'
        for each
    #macro foo( 'parameters' )

in every standardized include.
One draw-back to this approach though, is the current 256-character limit.

Some sort of 'usage protocol' would be helpful in the development of
specialized POV-Ray editors too.

Post a reply to this message

Randall Sawyer wrote:
> Would it be helpful to establish a way to view the 'usage text' of a macro
> without having to load its entire include file into an editor?
> 
> One solution would be to require a
> 
>     #declare foo_usage = 'string literal'
>         for each
>     #macro foo( 'parameters' )

A better solution (and avoiding the 256 character limit) is a simple

#declare help = true; // uncomment this to print help text
// #declare help = false; // uncomment this to suppress help text

in the main file.  Then, in your include files, do a

#if (help=true)
  #debug "Macro: make_widgets(PIPES, CHRONOTRONS) by Chris O'Donnell.\n"
  #debug "Usage:\n"
  #debug " PIPES should be a vector representing the color of the 
widgets.\n"
  #debug " CHRONOTRONS should be a string literal to be printed in the 
uppper left corner of the screen.\n"
#end

Or something along these lines, customized for each macro :)

...Chambers

Post a reply to this message

Ben Chambers <ben### [at] pacificwebguycom> wrote:
> #declare help = true; // uncomment this to print help text
> // #declare help = false; // uncomment this to suppress help text

Nice :)

I have something specific in mind though...

I'll post a new thread, since I think I'm about to go a little off-point
from this discussion.  I'll call it "POV Editors".

-Randall

Post a reply to this message

Randall Sawyer wrote:
> Would it be helpful to establish a way to view the 'usage text' of a macro
> without having to load its entire include file into an editor?
> 
> One solution would be to require a
> 
>     #declare foo_usage = 'string literal'

Have a look at perl .pm files. they use a special form of markup to make the
documentation. e.g.

  http://world.std.com/~swmcd/steven/perl/module_pod.html

real-world example:

  http://search.cpan.org/src/WADG/GD-Graph3d-0.63/lib/GD/Graph3d.pm

It also handles things such as dependencies etc. In POV there's no reason why
we could not use specially-formatted comments. (This is already regular
practice for C++, with various docgen tools helping to fill it out).

if a similar system was in place with POV, there's no reason why a POV editor
can't pick up the info automatically and show help for a macro (particularly
when typing in the definition to use it).

-- Chris

Post a reply to this message

John VanSickle wrote:
> * #namespace LABEL creates the namespace LABEL if it doesn't already 
> exist.  Whether new or not, namespace LABEL becomes the active namespace 
> (the former namespace is saved on a stack).
> 
> * #namespace undef pops the current namespace off of the stack, and the 
> former namespace becomes active.
> 
> * All #declare and #local statements affect the variable in the current 
> namespace.  Other variables of the same name in other namespaces are not 
> affected.

my personal opinion is that namespaces should have block scope (so are
delimited by a specific start and end, either with braces or a # declaration
of some sort). preferably with braces.

also namespaces must be properly nested within a source file; if you open a
namespace in a file, it must be closed before EOF in that file. otherwise you
run the risk of loading a include file and finding the current namespace has
changed afterwards.

finally, if we're going to change the way macros work with respect to scope,
we're better off changing them entirely (otherwise we run into compatibility
issues) and coming up with a new name for them (i.e. not #macro).

-- Chris

Post a reply to this message

my 2 cents:

We should not forget povray is heavily used by non-programmers and adding
more stuff -- like more syntax items or heavy-handed standards -- may put
some of these people down...

The main problem is naming collisions.  This problem may not even require
adding more syntax, but just handle the #include more gracefully -- perhaps
as a rewrite rule indeed.

Today, when I #include a file, its declarations may conflict with previous
ones.  When such a thing happens, povray should *warn* the user and suggest
using an alias for the included file and access its contents via the alias.

i.e., supposing both includes declare a make_bike:

#include "nem_bike.inc" #as nem // bike by nemesis
#include "jvs_bike.inc" #as jvs // bike by John VanSickle

object { nem_make_bike() translate -x*5*m }
object { jvs_make_bike() translate x*3*m }

If #as isn't used, it behaves just like regular #include... of course,
include files in the include files repository could be preprocessed like
that to make the uniquely prefixed by the author's login initials...

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:

> We should not forget povray is heavily used by non-programmers and adding
> more stuff -- like more syntax items or heavy-handed standards -- may put
> some of these people down...

I think I've got it!

In our ini files, each of us has default settings for variously-leveled
parameters:
image resolution, render quality, antialias tolerance, etc.

Why not have a tiered system whereby each user can establish how strictly or
loosely they want there includes governed?

Then, when the collection is up-and-running, the subgroups in the collection
could reflect the include regulator levels in the ini file.

If someone with strict standards really wanted to use something from a more
casual source, then it's caveat emptor.

Also, I think that the "#include ... #as" idea is more dynamic and flexible
than the #namespace approach.

-Randall

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:
> Today, when I #include a file, its declarations may conflict with previous
> ones.  When such a thing happens, povray should *warn* the user and suggest
> using an alias for the included file and access its contents via the alias.
>

My worry would be about files that are expecting to see a global variable by
one name and get the prefixed version instead.  It seems like the scope of
#as would have to cover any files that the #included file depends on.

Charles

Post a reply to this message

"Charles C" <nomail@nomail> wrote:
> My worry would be about files that are expecting to see a global variable by
> one name and get the prefixed version instead.

but the alias is given by the user of the include file in his own file.  So,
the prefix is necessary and he is well aware of it, since it was him who
named it in the first place.

> It seems like the scope of
> #as would have to cover any files that the #included file depends on.

perhaps an example could illustrate the situation better?

Post a reply to this message

Re: #include ... #as

Assuming that every include file's name is unique, then the real concern is
the names of the #macros and #declares within.  What about some sort of
name registration process along the lines of domain-name registration?

Once an include is accepted, then the names of its #macros and #declares are
nolonger available within later include files.

One approach which might make this process more manageable, would be to
require that each #macro/#declare name contain an abreviation which
identifies the type of object it returns ( light_source => foo_ls, texture
=> foo_tx, CSG => foo_cg, mesh => foo_mh, etc.).

-Randall

Post a reply to this message

nemesis wrote:
> "Charles C" <nomail@nomail> wrote:
>> My worry would be about files that are expecting to see a global variable by
>> one name and get the prefixed version instead.
> 
> but the alias is given by the user of the include file in his own file.  So,
> the prefix is necessary and he is well aware of it, since it was him who
> named it in the first place.
> 
>> It seems like the scope of
>> #as would have to cover any files that the #included file depends on.
> 
> perhaps an example could illustrate the situation better?
> 
> 
> 

If I understand correctly, the proposed #as would do what, add a prefix
to everything that the include makes available to the outside?

Okay, there would be two ways of handling the following:

#include "nem_bike.inc" #as nem // bike by nemesis

Everything in just bike.inc is prefixed with nem. If bike.inc includes
another file, are those prefixed or not? If not, we run the risk of name
overlap again because those items are probably going to be less likely
to be checked. If they are, how will bike.inc know what variable names
to call?

Will #as tags stack like namespaces, or when a new one is created is the
last one automatically closed?

Post a reply to this message

"Randall Sawyer" <sra### [at] yahoocom> wrote:
> One approach which might make this process more manageable, would be to
> require that each #macro/#declare name contain an abreviation which
> identifies the type of object it returns

yes, yes, i believe this kind of "Hungarian Notation" is used by most
povvers.  But if we require that each include file #declare gets prefixed
by a unique identifier, we'll endup with limits to the number of include
files and it is indeed too confusing.  Why can't i call my make_bike macro
simply make_bike within my own include file?  Just because the name will
clash with someone else's make_bike?  This is why i like aliases, since
they allow us to decide what to call someone else's #declares...

Post a reply to this message

Sabrina Kilian wrote:
> If I understand correctly, the proposed #as would do what, add a prefix
> to everything that the include makes available to the outside?

FWIW, in my experience, by the time the conversation gets to this level, 
progress has stalled to the point where nothing will get done because 
it's never perfect enough to start. Given that there isn't, at this 
time, any sort of problem along these lines, and given that the 
repository is a source-code repository with a license that allows such 
things to be fixed if it becomes a problem, it's probably better to get 
started, rather than to wait for POV-Ray to be improved to the point 
where a giant repository could be compiled without assistance.

-- 
   Darren New / San Diego, CA, USA (PST)
     Scruffitarianism - Where T-shirt, jeans,
     and a three-day beard are "Sunday Best."

Post a reply to this message

Perhaps a better solution, to avoid both namespace collisions and 
automatic name mangling, would be to add a new object type, the 
'container'.  It would work something like this:

#declare stuff = container;
#declare stuff.x = 5;
#declare stuff.loc = <3,4,6>;
#declare stuff.ball = sphere {0,1}

Basically, the container acts as a namespace on its own.  Each include 
file could use a container for its variables and declarations, except 
for those it needs exported globally.

...Chambers

Post a reply to this message

From: Sabrina Kilian
> If I understand correctly, the proposed #as would do what, add a prefix
> to everything that the include makes available to the outside?

Prefixing should be an easy option than to actually mess with povray's
parser to really cope with lexical scoping.

> #include "nem_bike.inc" #as nem // bike by nemesis
> Everything in just bike.inc is prefixed with nem. If bike.inc includes
> another file, are those prefixed or not?

If bike #includes a file and gives it an alias, that alias should actually
be of #local scope.  So, the #included items should only be visible inside
bike.inc.

Perhaps you're making confusion between #including bike's contents to your
file and the contents bike.inc #includes from other files?  The latter
should not be visible outside bike.inc.  I'm guessing povray's parser
could give a help by handling it transparently like:

/* bike.inc */

#include "nuts_and_bolts.inc" #as nuts

This would be handled by povray's parser as follow:  create in bike.inc
prefixed #locals for each #declared items in nuts_and_bolts.inc.  Will it
work?  I don't really know, but it's an idea.


From: Darren New
> FWIW, in my experience, by the time the conversation gets to this level,
> progress has stalled to the point where nothing will get done because
> it's never perfect enough to start.

Yes, i agree.  But give it some more time for more people to have some input
into this discussion.  Some planning can never hurt, only if remains just
planning...

> it's probably better to get started, rather than to wait for POV-Ray to be
> improved to the point where a giant repository could be compiled without assistance.

I'm also eager to get it going! :)


From: Ben Chambers
> Perhaps a better solution, to avoid both namespace collisions and
> automatic name mangling, would be to add a new object type, the
> 'container'.  It would work something like this:

#declare stuff = container;
#declare stuff.x = 5;
#declare stuff.loc = <3,4,6>;
#declare stuff.ball = sphere {0,1}

hmm, whatever happens if i #include a file that #declares a "stuff"? :)

> Basically, the container acts as a namespace on its own.  Each include
> file could use a container for its variables and declarations, except
> for those it needs exported globally.

Actually, your container looks remarkably similar to an "class instance"...
but, how is the container any different from a #macro?  They look the same,
except you have to prefix each variable with the "macro" name.

Post a reply to this message

hello, here's some more food for thought regarding aliased includes:


/* test.pov */
#include "test1.inc"


light_source { 4-8*z 1 }

object { test1_sphere
        //texture { t_sph }
        //texture { test2_t_sph }
        translate z*5
}

/* test1.inc */
#include "test2.inc"

#local test2_t_sph = t_sph // <- *1* povray parser makes included declare
local to this file...

#declare test1_sphere = sphere { 0, 1
        texture { test2_t_sph } // <- ... we use it prefixing with our
chosen alias ...
}

#undef t_sph // <- *2* ... and undef all included #declares at the end


/* test2.inc */
#declare t_sph = texture {
        pigment { rgb y }
        finish { diffuse .6 phong .9 phong_size 50 }
}


It works well. If you uncomment the given textures in test.pov, it won't
render, since the symbols are hidden as expected.

So, if povray's parser gives us a help in making steps *1* and *2* a
reality, we can get better symbol scoping with very little effort.

Post a reply to this message

As I've shared before, I am a hands-on learner.  So, I have set up an actual
scenario for myself to experiment with.  I would also like to share it with
all of you.

I am posting an attachment at povray.binaries.scenes-files (look for
Standards Challenge).  It is a folder called "SRS.StandardsChallenge".  In
the folder are three files: "povver1.inc", "povver2.inc" and "scene.pov".

In the first file, there are definitions for the #macros "ball", "rod" and
"block" as well as a definition for the macro "p1_donut".

The second file contains definitions for the #macros "ball", "rod", "block"
and "p2_donut".

The scene file calls the #macros "ball", "rod", "block, "p1_donut" and
"p2_donut".
By reversing the order of the two #include lines in "scene.pov", you get a
different result.

The challenge is to use existing POV-Ray SDL to modify the three files,
presenting them as two (rewritten) *.inc files and eight *.pov files - one
for each possible outcome.

Post a reply to this message

Solution to Challenge:  Is it generally extensible?

You can download my solution to my own challenge at aforementioned site.

Here is what I came up with:

In "povver1.inc":
    On the first line:
        // Use #declare whose = "povver1"
    On the two lines immediate preceeding any #macros or #declares:
        #ifdef ( whose )
            #if ( !strcmp(whose, "povver1") )

        *** macros and declares go here ***

    On the two lines immediately following any #macros or #declares:
            #end//(whose = "povver1")
        #end//ifdef(whose)

In "povver2.inc":
    The same as in "povver1.inc", replacing "povver1" by "povver2"

In any scene file:
    #declare whose = "povver1"
    #include "povver1.inc"

    stuff from "povver1.inc" you want to have in scene - modified or not

    #declare whose = "povver2"
    #include "povver2.inc"

    stuff from "povver2.inc" you want to have in scene - modified or not
    [ Nothing unique to "povver1.inc" file is lost, making it possible to
combine items from two-or-more include files. ]

Additional added value to this approach:  Author recognition!
By requiring that every include file make use of '#declare whose', a
scene-writer will be making an acknowledgement of the original author from
whom
they are borrowing.  It will be written into the text of their scene file.

Will this work?  Is there something I'm missing?

-Randall

Post a reply to this message