The Persistence of Vision Raytracer (POV-Ray).

This is the legacy Bug Tracking System for the POV-Ray project. Bugs listed here are being migrated to our github issue tracker. Please refer to that for new reports or updates to existing ones on this system.

Attached to Project: POV-Ray
Opened by Benedikt Adelmann - 2013-06-29
Last edited by William F Pokorny - 2017-02-07

FS#299 - Object Properties Feature

Up to POV-Ray 3.7 RC7 it has not been possible so far to declare custom properties for POV-Ray’s objects, which would be especially useful for complex objects defined in include files.

Currently, if you want to have an object (e.g. a car) with certain variable parameters (e.g. colour, wheel rotation, ...) defined in an include file and the parameters set by a scene file which uses the include file, you have to choose one of the following approaches:

1. use a macro

#macro car(colour, wheelrot, ...)

or, 2. check parameters declared before, e.g.

#declare car =
union {
  #ifdef (colour)
    #local colour_internal = colour;
    #local colour_internal = default_colour;

The resulting object would be used in the following way:

  #include "car.inc" // include file once
  object {
    car(rgb <1,0,0>, 0, ...) // macro approach
  // other approach
  #declare colour = rgb <1,0,0>;
  #declare wheelrot = 0;
  #include "car.inc" // include file every time you want to have a car object instance
  object {

Needless to say, both approaches are not quite optimal.

  • The macro approach needs only one #include directive and name conflicts will (hopefully) not be a problem. However, one would have to look up the parameter order of the macro in the include file, in the worst case every time the macro is used.
  • The other approach needs as many #include directives as car objects shall be instantiated, there can arise name conflicts with other inculde files used in the scene, and a (potentially long) list of parameters has to be declared before each #include. On the other hand, with this approach for any value it is clear which information it gives, e.g. #declare colour = rgb <1,0,0> can easily be read as ‘set car colour to “red”‘.

My suggestion would be creating an SDL feature to

  • declare which properties a certain object can have
  • set these properties inside the object statement in which the object is used.

One step up could be to even declare object classes along with them.

This could look like this:

// include file code
class car { // alternatively (without classes) use #declare car = object { ...
  property colour = rgb <1,0,0>; // with default colour
  union {

// scene file code
car { // alternatively (without classes) use object { car ... }
  colour rgb <0,0,1>

Note that this solution makes the declarations much more concise and easy-to-read. Especially in scenes with many includes and animation scenes where objects’ properties have to be manipulated according to sometimes complex functions, this would be very useful. Please also consider that such user-defined objects can have dozens of properties.

Grimbert Jérôme commented on Saturday, 29 June 2013, 12:24 GMT

This seems like the old opposition between positional language and keyword arguments based language.


(I like their opposition of Java & Objective-C)

Traditionnaly, the SDL was rather positional, with a few exceptions like a part of the camera (yet, the type of camera must still be in first position).

keyword is no excuse for not documenting a macro, and no excuse either to not read the documentation.

Yet, I wonder if documenting for doxygen would be possible (using doxygen formal comments), to ease the search and usage of all macro and objects.

I like positional better than named, because named imply too much verbosity (you cannot have a default order, and having to write "sphere{ center <0,0,0> radius 2 }" is not what I'm used to.

Benedikt Adelmann commented on Saturday, 29 June 2013, 13:31 GMT

I would not suggest making the SDL entirely keyword argument based, but what my suggestion would mean is a slight move towards data structures / "objects" in SDL. SDL does not need to become an object-oriented language (too major a change I think), but consider the JavaScript / C example in the "With data structures" section of the Wikipedia article. I had somethink similar to that in mind when writing this feature request. That way, SDL could stay positional yet allow keyword arguments.


void doSomethingWithCar(Colour BodyColour, Colour MirrorColour, RearType Rear, int CowlLength, int NumberOfDoors,
                        int WheelRotation, int BootLidRotation, int CowlRotation, int[][] DoorRotations)

In Java or any other object-oriented language, something like the following would be more appropriate:

void doSomethingWithCar(Car ACar) // Car class encapsulates car's properties

// if doSomething is a method of class Car

Defining methods in SDL does probably go a bit too far.

keyword is no excuse for not documenting a macro, and no excuse either to not read the documentation

Yes indeed, but when you look at your scene again a year after you have written it and if you just want to change one parameter of one object, you do probably not want to read the documentation (although it is not too much effort).

I wonder if documenting for doxygen would be possible

That would anyway be useful. Additionally it would be nice then if POV-Ray's editor window could display a documentation popup if needed.

Finally, another advantage of data-structure-like custom objects in SDL would be that if a parameter was added to an object (class) after that class has already been in use, it would not be necessary for everybody who uses it to update the macro call code (just the default value would be used). Currently, this could be achieved with the second approach I described, but that approach leads to very high verbosity indeed.

Grimbert Jérôme commented on Saturday, 29 June 2013, 14:47 GMT

The problem with data-structure-like custom object for optional paramater in macro is that it would need open strong typing (defined by user) (whereas current SDL know of only limited object (object, material, texture, pigment,... vector, float, string). Not impossible, but might be expensive to implement.

Maybe an alternate solution to the subconscious issue might be the support of default values for macro. (even allowing something like "Car(,,,SteerWheelAngle) " and "Car(,,,,,,,,Blue)" with a "#macro Car(Pigment=pigment{color Black}, Heading=0, ..."
It is not easy either, but avoid at least user-defined type/class (which are not supported at all so far)

Benedikt Adelmann commented on Saturday, 29 June 2013, 18:42 GMT
The problem with data-structure-like custom object for optional paramater in macro is that it would need open strong typing

I do not see that, why?

  • The parameters (of a data structure) need not be strongly typed.
  • Any variable holding a custom object / data structure as a value need not be typed (however, the time it is assigned to scene by an object {} block it has to be known the exact class if classing is implemented)

If I have gotten something wrong and there actually is a problem, you could do something like other scripting languages, e.g. JavaScript: introduce Dictionary objects which can hold arbitrary values associated with names. The items could then be extracted like car_dict["wheel_angle"] (with or without quotes) or using dot notation, e.g. car_dict.item("wheel_angle"). This would be similar to the issue discussed in FS#129.

Christoph Lipka commented on Monday, 15 July 2013, 22:01 GMT

Going back to what I guess is the original intention of the feature request: A feature to define arbitrary custom "primitives" with the same syntax as the built-in primitives is high on the agenda of at least some members of the dev team; it will probably come as part of a major overhaul of the parser and revision of the SDL.

Benedikt Adelmann commented on Tuesday, 16 July 2013, 11:56 GMT
A feature to define arbitrary custom "primitives"

Yes, I think that fits the problem I had in mind writing this feature request. I did not know though that such a feature (i.e. to that extent, which apparently seems to be a major change) had already been planned.

William F Pokorny commented on Tuesday, 07 February 2017, 13:52 GMT

Now tracked on github as issue #233.


Available keyboard shortcuts


Task Details

Task Editing