. .
Next: Aggregate Objects Up: Object Definition Previous: The World Object

# Primitives

Primitive objects are the building box with which other objects are created. Each primitive type has associated with it specialized methods for creation, intersection with a ray, bounding box calculation, surface normal calculation, ray enter/exit classification, and for the computation 2D texture coordinates termed u-v coordinates. This latter method is often referred to as the inverse mapping method.

While most of these methods should be of little concern to you, the inverse mapping methods will affect the way in which certain textures are applied to primitives. Inverse mapping is a matter of computing normalized u and v coordinates for a given point on the surface of the primitive. For planar objects, the u and v coordinates of a point are computed by linear interpolation based upon the u and v coordinates assigned to vertices or other known points on the primitive. For non-planar objects, uv computation can be considerably more involved.

This section briefly describes each primitive and the syntax that should be used to create an instance of the primitive. It also describes the inverse mapping method, if any, for each type.

blob thresh st r ^p [st r ^p ... ]
Defines a blob with consisting of a threshold equal to thresh, and a group of one or more metaballs. Each metaball is defined by its position ^p, radius r, and strength st.

The metaballs affect each other according to a superimposed density distribution:
F(x,y,z) =
There is no inverse mapping method for blobs.

Multi-surfaced blobs have been implemented, at this time, as a new object. This object is called a cblob. Anything you can do to a blob you can do to a cblob. Except the syntax is slightly different in that it has, after each coordinate triple for a metaball, the metaball's particular surface specification.

cblob thresh st r ^p [st r ^p ... ] surface
Defines a multi-surfaced blob with consisting of a threshold equal to thresh, and a group of one or more metaballs. Each metaball is defined by its position ^p, radius r, and strength st and has its own surface specification.

box ^corner1 ^corner2
Creates an axis-aligned box which has ^corner1 and ^corner2 as opposite corners.

Transformations may be applied to the box if a non-axis-aligned instance is required. There is no inverse mapping method for boxes.

Creates a sphere with the given radius and centered at the given position.

Note that ellipsoids may be created by applying the proper scaling to a sphere. Inverse mapping on the sphere is accomplished by computing the longitude and latitude of the point on the sphere, with the u value corresponding to longitude and v to latitude. On an untransformed sphere, the z axis defines the poles, and the x axis intersects the sphere at u = 0, v = 0.5. There are degeneracies at the poles: the south pole contains all points of latitude 0., the north all points of latitude 1.

torus rmajor rminor ^center ^up
Creates a torus centered at ^center by rotating a circle with the given minor radius around the center point at a distance equal to the major radius.

In tori inverse mapping, the u value is computed using the angle of rotation about the up vector, and the v value is computing the angle of rotation around the tube, with v=0 occurring on the innermost point of the tube.

triangle ^p1 ^p2 ^p3
Creates a triangle with the given vertices.

triangle ^p1 ^n1 ^p2 ^n2 ^p3 ^n3
Creates a Phong-shaded triangle with the given vertices and vertex normals.

For both Phong- and flat-shaded triangles, the u axis is the vector from ^p1 to ^p2, and the v axis the vector from ^p1 to ^p3. There is a degeneracy at ^p3, which contains all points with v = 1.0. This default mapping may be modified using the triangleuv primitive described below.

triangleuv ^p1 ^n1 ^uv1 ^p2 ^n2 ^uv2 ^p3 ^n3 ^uv3
Creates a Phong-shaded triangle with the given vertices, vertex normals. When performing texturing, the uv given for each vertex are used instead of the default values.

When computing uv coordinates within the interior of the triangle, linear interpolation of the coordinates associated with each triangle vertex is used.

poly ^p1 ^p2 ^p3 [^p4 ... ]
Creates a polygon with the given vertices. The vertices should be given in counter-clockwise order as one is looking at the ``front'' side of the polygon. The number of vertices in a polygon is limited only by available memory.

Inverse mapping for arbitrary polygons is problematical. Rayshade punts and equates u with the x coordinate of the point of intersection, and v with the y coordinate.

heightfield file
Creates a height field defined by the altitude data stored in the named file. The height field is based upon perturbations of the unit square in the z=0 plane, and is rendered as a surface tessellated by right isosceles triangles.

There is a description of the format of a height field file and a description on how to create heightfield files using Rayshade. Height field inverse mapping is straight-forward: u is the x coordinate of the point of intersection, v the y coordinate.

plane ^point ^normal
Creates a plane that passes through the given point and has the specified normal.

Inverse mapping on the plane is identical to polygonal inverse mapping.

Creates a cylinder that extends from ^bottom to ^top and has the indicated radius. Cylinders are rendered without endcaps.

The cylinder's axis defines the v axis. The u axis wraps around the cylinder, with u=0 dependent upon the orientation of the cylinder.

Creates a (truncated) cone that extends from ^bottom to ^top. The cone will have a radius of rad_bottom at ^bottom and a radius of rad_top at ^top. Cones are rendered without endcaps.

Cone inverse mapping is analogous to cylinder mapping.

Creates a disc centered at the given position and with the indicated surface normal.

Discs are useful for placing endcaps on cylinders and cones. Inverse mapping for the disc is based on the computation of the normalized polar coordinates of the point of intersection. The normalized radius of the point of intersection is assigned to u, while the normalized angle from a reference vector is assigned to v.

fracland [ surface ] seed subdiv
This primitive creates a fractal surface centered at x = 0.5, y = 0.5 and ranging from x = y = 0 to x = y = 1. It is actually a heightfield primitive that is generated within rayshade rather than being read in from a file.

The seed value is the seed for the random number function. The seed value specifies the shape of the surface - changing the seed value will randomly change the surface shape.

The subdiv value is the number of subdivisions for the surface - subdiv = 0 will produce a flat square, subdiv > 0 will produce a square with an ever more detailed surface. So far, rayshade seems to have trouble with subdivisions greater than eight (if anyone finds otherwise please tell me!!) and produces surfaces with "holes" in it for values greater than this.

The number of points in the surface follows the following formulas:

size (number of points per side) = (2^subdiv) + 1
total points = size^2
The four corner points will always have an altitude of 0, the maximum altitude should never be more than 1.0 and the minimum altitude should never be less than -1.0.

sweptsph SweptSphCenter r0 r1 r2 r3
This primitive is defined as a sphere of varying radius swept, or extruded along a path in space. The path is defined in one of several ways as defined by SweptSphCenter which can be one or more of:
bezier x0 y0 z0 x1 y1 z1 x2 y2 z2 x3 y3 z3
coeffs cx0 cx1 cx2 cx3 cy0 cy1 cy2 cy3 cz0 cz1 cz2 cz3
xbezier x0 x1 x2 x3
ybezier y0 y1 y2 y3
zbezier z0 z1 z2 z3
xcoeffs cy0 cy1 cy2 cy3
ycoeffs cz0 cz1 cz2 cz3
zcoeffs cz0 cz1 cz2 cz3

The path can either be defined as four points which define a bezier path, where the path passes through the first and last endpoints with the second and third points defining the slope or tangent line for the curve at the first and last points. This is specified as bezier p1 p2 p3 p4 where pn is an x, y, z triplet.

A second way to define the curve is to specify the coefficients for the parametric equations that define the curve. This is specified as coeffs fx fy fz where each fn is a third order equation, c0 c1 c2 c3, where:

fn = c0 + c1*x + c2*x^2 + c3*x^3.
A third way is to use any combination of parametric bezier curves or function coeffs. These are specified as nbezier or ncoeffs where n is x, y, or z. These are followed by four numbers that are interpreted as the coefficients for the parametric variable x, y, or z in the case of ncoeffs or as the bezier curve where the first number is the starting value, the last value is the ending value, and the second and third values define the "speed" at which the curve leaves the endpoints.

The radius is specified as four numbers which are the coefficients for a third order equation over the interval [0,1]. This is specified as r0 r1 r2 r3 where:

r(x) = r0 + r1*x + r2*x^2 + r3*x^3.
Both the radius and the center equations are evaluated on the interval [0,1].
```
sweptsph bezier	0 0 -3  2 0 0  3 0 0  0 0 3
-0.5 1 0 0

eyep    0 -30 0
sweptsph bezier	-10 0 0  -10 0 10  10 0 -10  10 0 0
1 0 0 0

eyep    0 -20 0
lookp   0 0 5
sweptsph coeffs	.65 15.7 -22.2 0  0 0 0 0   1 56 -110 65.5
1 -1 0 0

eyep    0 -30 0
sweptsph xbezier	0 10 -10 0
ycoeffs	0 10 -10 0
zbezier	10 0 0 -10
.5 6 -6 0```

The rotspline primitive enables solids of revolution to be rendered.

rotspline ^base ^apex coeffs c3 c2 c1 c0
rotspline ^base Rbase Gbase ^apex Rapex Gapex
Rotates the curve r^2 = c3*x^3 + c2*x^2 + c1*x + c0 with either the coefficients themselves or the radius and gradient of the ends of the curve can be specified. ^base is the position of the centre of one end and ^apex is the centre of the other. Rbase is the radius at the base and Gbase is the gradient at the base. Likewise for Rapex and Gapex.

See an example.

. .
Next: Aggregate Objects Up: Object Definition Previous: The World Object

Jelle van Zeijl (jvzeijl@iso.estec.esa.nl)
Wed Jun 15 16:19:08 MET DST 1994