AUTOMATIC CLOCK MODIFIER MACRO FILE for Persistence of Vision 3.1

Created by Chris Colefax, 7 August 1998


INSTALLATION

QUICK START

GENERAL USAGE

USING SPECIFIC MACROS

COPYRIGHT AND LEGAL INFORMATION

CONTACTING THE AUTHOR


INSTALLATION
The Automatic Clock Modifier macro file, AutoClck.mcr, contains a collection of macro definitions that use the Clock Modifier include file to animate various elements of a POV-Ray scene file. After installing the Clock Modifier include file you should also copy AutoClck.mcr to one of the directories (folders) in your POV-Ray library path. Normally this is the INCLUDE sub-directory of the directory where you installed POV-Ray, so if you installed POV-Ray in C:\POVRAY you should copy the AutoClck.mcr file to C:\POVRAY\INCLUDE. On a Windows 95 system, this is probably something like:

C:\Program Files\POV-Ray for Windows\Include

On UNIX and similar systems, where filenames are case-sensitive, you may have to rename the macro file so the capitals and lowercase are as shown above. This will enable you to render the sample files without modification.


QUICK START
The Automatic Clock Modifier macros are designed to make animating scenes using the Clock Modifier include file much quicker and easier. Rather than declaring the clock_type, clock_start, and clock_finish options, then including ClockMod.inc, and then using the resulting mclock variable with the necessary equations, the macros can simply be used like this:

#include "AutoClck.mcr"

object {MyObject
scale From (.4, 1) To (.8, <1.5, .5, .75>) To (.95, .01))
translate From (0, <-5, 10, -14>) To_Using (.75, <10, 5, 0>, "S-Curve")
}

As you can see, each pair of brackets contains at least two values: the first is a clock value, while the second is the value you want to use at that clock value. In this way, you can specify a list of practically unlimited points and/or values that you want to use at any point in time of your animation. And in addition to controlling object transformations (like above), you can use the macros to animate any POV-Ray parameter that uses a float or vector value, and you can also blend between unlimited pigments, textures, and other map values. You can also use simple macros to specify the clock_type for each transition, or to take full advantage of the clock_repeat, clock_strength, and clock_combine options - without ever having to declare them manually.

Note that to use any of the macros in a scene, you only need to include the macro file once (at the beginning of the scene, before you use any of the macros).


GENERAL USAGE
As mentioned above, the Automatic Clock Modifier macros can be used to animate smooth transitions between an unlimited list of floats/vectors, pigments, textures, and more. In each of these cases (referred to as properties), specific macros must be used. However, the general syntax in each case remains the same; the first step is to specify when you want the property you are animating to start changing, and what value you want to use for the property up to this time, using the appropriate From () macro, eg:

translate From (.5, <-10, 5, 6>)

or

texture {Texture_From (0, ShinyGold)

In the first example, the object you are translating starts the animation at <-10, 5, 6> and remains there until the clock reaches 0.5. The texture of the object, on the other hand, starts the animation as ShinyGold, and immediately starts blending to the next texture specified. The next step is to specify the value you want for the property, and when you want the property to equal the new value, eg:

translate From (.5, <-10, 5, 6>) To (.75, < 4, 6, 2>)

This specifies that the object will be positioned at <-10, 5, 6> until the clock reaches 0.5, after which the object will move to < 4, 6, 2> by the time the clock reaches 0.75. After this time, the object will remain at < 4, 6, 2> unless you specify additional To () points and clock values. The list you use can be as long as you like, but obviously the clock value in each To () statement must be greater than the clock value in the previous To () statement. If you want to change the property's value instantly, rather than animate a smooth transition, you can use the same clock value twice, eg:

scale From (.3, 1) To (.3, 2)

In this case, the object remains at normal size until the clock reaches 0.3, at which time it suddenly becomes double its previous size. On the other hand, if you want the property's value to remain static for a period, you can use the same property value twice, and only change the clock values, eg:

rotate From (0, 0) To (.3, y * 180) To (.6, y * 180) To (.8, 0)

The object starts the animation by rotating from its normal orientation to being flipped about the y axis. When it reaches this new rotation (at clock = 0.3) it remains in this position until the clock reaches 0.6. After this it returns to its original orientation, by the time the clock reaches 0.8.

In all of the above cases, the properties' transitions between one value and another happened linearly (ie. they moved at the same speed from one value to the next, and stopped and started suddenly at each of the specified clock values). In most cases, however, you will want to take advantage of the various clock types offered by the Clock Modifier include file to create transitions of various types, such as acceleration, smooth s-curves, jumping, oscillations, etc. To specify the clock type to be used for each transition, use the To_Using () statements and add the clock type as the final argument, eg:

sphere {<0, 0, 0>, From (0, .2) To_Using (.4, 1, "Accelerate") To_Using (1, .3, "Wave")}

As you can see, the sphere starts the animation with a radius of 0.2, which accelerates to a radius of 1 (at clock = 0.4). After this, the sphere's radius changes to 0.3 (when clock = 1). However, this final transition uses a Wave clock, and this means that the sphere's radius starts at 1 (clock = 0.4), smoothly changes to 0.3, and then changes back to 1 (at clock = 1).

This effect will occur with a number of the other available clock types, such as Oscillate, Recoil, Jump, and Bounce. In the case of the latter, note that the behaviour of the modified clock is slightly different than when using the Clock Modifier include file in the usual manner. Rather than starting high, falling, and then rising again, the Bounce clock will start at the position you specify, Bounce to the next specified position, and then return to the original, eg:

translate From (0, y * 10) To_Using (.67, 0, "B") To_Using (1, < 15, 10, 5>, "D")

Using these options, the object bounces from y * 10 down to y * 0, and then back up again, before decelerating to < 15, 10, 5> (note that only the first letter of the clock type is required).

More advanced effects can be obtained with the Using () statement. This allows you to specify clock_type, clock_strength, clock_repeat, and optional clock_combine values to use with the Clock Modifier include file. By default, each time you use a From () statement, all the clock options are reset to their defaults (Linear clock type, with a strength and repeat of 1, and no combination clock). You can change these by adding a Using () statement directly after the From () statement, before the To () statements you want the options to apply to, eg:

light_source {<-15, 10, -25> rgb From (0, 0) Using ("A", 2, 1, "") To (.3, .5) Using ("O", 1, 5, "D") To (1, 1)}

The light source's colour starts at 0, accelerates with a strength of 2 to 0.5 (at clock = 0.3), and then oscillates to a value of 1 at clock = 1, repeated 5 times. The oscillations are combined with a deceleration, so the waves increase in length as the animation progresses. Another interesting effect can be achieved by using a repeat value that is not a whole number, eg. you could specify Using ("W", 1, 1.5, "") to give a Wave that is repeated one and a half times.

Note that the clock options are only reset after a From () statement - otherwise, the options you set either with a Using () statement or To_Using () statement apply to all subsequent To () statements. This means you can use, say, the S-Curve clock type to animate smooth transitions between a whole list of values, eg:

pigment {rgb < 1, 1, 1> transmit From (0, 1) Using ("S", 1, 1, "") To (.2, .5) To (.5, .8) To (.7, 0) To_Using (1, 1, "D") ...

or, for an object that shoots out from the origin and then snaps back:

translate From (0, 0) Using ("Recoil", 1, 1, "") To (.1, < 5, 4, -3>) To (.2, x * -6) To (.3, < 1, -5, -1>) ...


USING SPECIFIC MACROS
All the examples in the above section show how the From (), To (), and To_Using () statements can be used to interpolate between vector and float values (or a mixture of both), wherever such values are expected/used by POV-Ray. The Automatic Clock Modifier macro file also includes macros that allow you to interpolate between declared floats/vectors, and map entries (including pigments, textures, and other map types). The specific syntax for these macros is shown below. Note, however, that the Using () statement can be used with any of the macro types.

DECLARED VARIABLES


Although the basic macros can be used in place of almost any float or vector value, POV-Ray does not allow them to be used following a #declare = or #local = statement. If you want to reuse a value calculated by the macros, or to nest calculated values within another series of From () ... To () statements, you should use the Declare_From (), Declare_To (), and Declare_To_Using () statements. Start by declaring the variable you want to use, with the initial value you want, eg:

#declare MyVar = 10; or #local Direction = <-15, 45, 90>

Then, call use Declare_From () statement, with the name of the variable and the first clock value you want to use, eg:

Declare_From (MyVar, .4)

Note that if the variable has been defined using the #local statement, the variable will remain a local variable even after using the Declare_From () statement. Also, if you wish to use vector values in the series, you should initially declare the variable as a vector (eg. #declare MyVar = < 10, 10, 10> instead of the above). You may now use the Declare_To () statement, or the Declare_To_Using () statement, with the variable name first, followed by the other options (as used by the basic macros), eg:

Declare_To (MyVar, .6, 25) Declare_To_Using (MyVar, 1, 0, "D")

This will change MyVar from 10 (at clock = 0.4) to 25 (at clock = 0.6), and then decelerate its value to 0 (at the end of the animation). This variable can now be used in the usual manner, including as part of another From () ... To () series (or Declare_From () ... Declare_To () series).

PIGMENTS AND TEXTURES


Although it is possible to use the basic macros to independently interpolate between all the numeric aspects of a pigment or texture, this method has its limitations. Fortunately, POV-Ray does provide an average map_type, and it is this which allows you to use either the Pigment_From (), Pigment_To (), and Pigment_To_Using () statements, or the Texture_From (), Texture_To (), and Texture_To_Using () statements, to interpolate between colours, pigments, and textures, using the complete range of clock options. The usage is as follows:

pigment {Pigment_From (0, rgb < 1, 1, 0>)
Pigment_To_Using (.5, pigment {bozo scale .3}, "W")
Pigment_To_Using (.6, rgbt 1, "D") }}

or:

texture {Texture_From (.2, MyTexture1) Using ("W", 1, 3, "A") Texture_To (.8, MyTexture2) }}

The above pigment starts (at clock = 0) as a plain yellow, uses a wave to change to a bozo (and return to the initial yellow), and then decelerates to a completely transparent pigment. Note that the pigment {} wrapper is required when you specify a full pigment, although it is not necessary when specifying colours or previously declared pigments. The above texture uses an accelerating, triple wave to blend between MyTexture1 and MyTexture2.

Note that while any of the available clock options can be used to blend between pigments or textures, some of the options might not give the results you're expecting. In particular, the Oscillate clock type will actually average the pigments/textures you specify using negative values, so:

sky_sphere {pigment {Pigment_From (0, rgb < .5, .5, .5>) Pigment_To_Using (1, rgb < 1, 0, 0>, "O") }}}

will blend the background from grey, to red, back to grey, and then to a cyan (the result of the grey and the negative of the red), before returning to grey.

Finally, you will notice from all the above examples that two closing brackets are used to close the pigment { or texture { statement. The extra closing bracket is required to close the pigment_map { or texture_map { statement that the Pigment_From () or Texture_From () statement creates for you.

MAP ENTRIES


Note: The following macros will not work with certain versions of the POV-Ray 3.1 beta - if you are unable to use them, you should obtain the latest version of POV-Ray.

In addition to blending pigments and textures, you can use the Automatic Clock Modifier macros to blend between any set of map entries, such as normals, or media densities. The syntax for the Map_From (), Map_To (), and Map_To_Using () macros is the same as for the macros used for pigment or texture map entries. However, you must specify the type of map you are creating, and the average map type, eg:

normal {average normal_map {
Map_From (.125, normal {bumps .1 scale < 2, 2, 1>})
Map_To (.6, MyNormal) }}

or:

density {average density_map {
Map_From (.05, MyDensity1) Using ("S", 1, 1, "")
Map_To (.345, MyDensity2) Map_To (.512, MyDensity3) Map_To (.96, MyDensity4) }}

CLOCK PREVIEW


The Automatic Clock Modifier macro file also allows you to preview clock types and options, including combination clocks. The syntax is the same as the Using () statement, ie:

Preview_Clock ([clock type], [clock strength], [clock repeat], [combination clock type])

The other clock preview options (graph_continuous, graph_thickness, and graph_smoothness) can be used by simply declaring them before using the Preview_Clock () statement (see the Clock Modifier for more information).


COPYRIGHT AND LEGAL INFORMATION
The Automatic Clock Modifier Macro File, including AutoClck.mcr, all documentation, and associated sample *.POV files are Copyright 1998 by Chris Colefax. Full permission is granted to the user to modify any or all of the files for his/her own use. If modified versions are to be distributed the user should make clear the modifications that have been made by him/herself.

The Automatic Clock Modifier Macro File may be bundled as part of the Clock Modifier Include File Package, with or without other software on CD-ROM collections, Bulletin Board systems and other file archives, providing that all associated files, including documentation and samples, are included. I would also request that persons intending to distribute the Automatic Clock Modifier Macro File in this manner or otherwise would first contact me to ensure that they are in possession of the latest available version.

Further, no restrictions of any sort are placed on the usage of the macro file itself (AutoClck.mcr), and scene files or images created using the macro file remain entirely the property of the user or users who have created them. I claim no liability or responsibility for damages or loss resulting from usage of the macro file, or any part of the macro file package.


CONTACTING THE AUTHOR
If you wish to contact me with bug reports, bug fixes, criticisms, comments, suggested improvements, questions, etc. you can reach me by email at:

ccolefax@geocities.com

or by regular mail at:


POV-RayTM and Persistence of VisionTM are registered trademarks of the POV-Ray TeamTM