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