intro modes commands objects attributes parameters timing variables, constants forces todo

Modes

version
angle
length
precision
hand
coordinate
color
time
mode

Modes are local to the file they appear in. Within that file modes may be changed as many times as wished, though that is to be discouraged as it could make for very hard-to-read code. The main place you are likely to find many changes of modes is in library files where it may make sense to define things in different modes to make the meaning of the definition clearer.

Modes get stored as special reserved variables (e.g. #version) which can be read by the language like any other variable. Most are read-only from within the scripting and can only be altered using the actual set command.

#version

Version should be stated at the top of each file. This allows features to be added to the core spec without breaking old content. It should be given at the top of all include files too. If you want to enable some old or new features the version can be changed at any point within a file, though that should be avoided where possibility as it risks impairing human readability.

Example:

set #version 0.2 set #version 1.1

#angle

Angles default to radians, but may be set to use degrees by setting it appropriately anywhere in a file. It may also be set to any format desired such as decimal fractions of a circle, where a whole circle is 1 and half a circle is 0.5, and so on. (radian/degree/gradient?)

Example:

set #angle degree set #angle 360 set #angle radian set #angle 6.28318530717958647692528676655901 set #angle 1 set #angle 100

#length

Length measurements are normally made in meters, but may be altered by setting length to a different unit. This provides a very simple way to combine files that use different measurements.

Example:

set #length 1000 //1 unit is a kilometer set #length km //1 unit is a kilometer set #length km*1000 //1 unit is 1,000 kilometers set #length 0.3048 //lets you give all measurements in feet set #length ft //lets you give all measurements in feet set #length 1609.34 //all measurements are in miles set #length mile //all measurements are in miles set #length au //all measurements are in Astronomical Units set #length ly //all measurements are in light years set #length lightyear //all measurements are in light years

#precision

This changes the mathematical precision of calculations. I doubt this can be changed at different places in the file, though there might be advantages to that (calculate position using 128 bit floating-point, but use small integers for timing, for instance). It may be worth considering whether to add a precision attribute too. Then the precision mode would be what all other calculations would default to. I need to think more about this mode.

Example:

set #precision 64 fixed //calculations use 64 bit fixed-point arithmetic set #precision 128 int //calculations use 128 bit integer arithmetic set #precision 32 float //calculations use 32 bit floating-point arithmetic

#hand

Handedness defaults to a left-handed universe (thumb points along x axis, index finger points up, middle finger points forward), but may be set to right-handed. (VRML is right-handed; POV-Ray is left-handed. Left-handed is more intuitive for the world builder because +Z is forward.)

Example:

set #hand left set #hand right

#coords

Coordinates can be set to rectangular or spherical frame of reference. This setting will only rarely be used. It is mostly a convenience for working on the surface of spherical worlds where x and z look like straight lines but are actually extremely large circles, and y is up away from gravity's pull. (I still need to work out all the ramifications of using this setting. What of north/south, east/west, up/down? Great circles of x and z are actually different to north and east, for example at the north and south poles east and west become meaningless, whereas x and z great circles always mean left/right and forward/back. Perhaps spherical coordinates should always be available through r u f , that is right, up, forward, being used instead of x y z in position and angle attributes.)

Example:

set #coords spherical set #coords rectangular

#color

Color may use various units. They are set by simply specifying the maximum number in the range.

Most common is 0 to 1 range, so that is the default.

Hardware uses 0 to 256 range and it is quite natural for some of us to use powers of 2 for such things. If the keyword hex is given then that is the same as using the number 256. Note that even if another mode is set, color can be given as a hexadecimal number and will be correctly interpreted. Hexadecimal numbers for color are written the same way they are in html (for example white is #ffffff or red fully on is r=#ff) with or without quotes.

Something that may feel more natural to many people and easier to write is 0 to 100 -- a percent system.

360 is a quite magical number, being evenly divisible by 20 other numbers: 2, 3, 4, 5, 6, 8, 9, 10, 12, 15, 18, 20, 36, 40, 45, 60, 72, 90, 120, 180
100 only has 7 divisors: 2, 4, 5, 10, 20, 25, 50
256 has only 7, and worse, they are all only even numbers 2, 4, 8, 16, 32, 64, 128

It is important to understand that changing the color setting normally doesn't affect the fact that color calculations generally use 8 bits per color. This can be changed by using the 'hdr' keyword.

If 'hdr' is used in the color mode then High Dynamic Range colors are used. These are expressed as rgbe, where 'e' is an 8 bit exponent. Read more about hdr colors at http://www.debevec.org/Research/HDR/.

Example:

set #color 100 set #color 1 set #color 1 hdr set #color hdr set #color 360 set #color 256 set #color 256 hdr