Section
5 - Geometric PrimitivesSection
5 - Geometric PrimitivesPolygons | Patches
| Quadrics | Procedural
Primitives | Implementation-specific
Geometric Primitives |
Solids and Spatial Set
Operations | Retained Geometry
The RenderMan Interface supports only surface- and solid-defining geometric primitives. Solid primitives are created from surfaces and combined using set operations. The geometric primitives include:
Points are used to construct polygons, patches and NURBS. Point positions can be either an (x,y,z) triplet ("P") or an (x,y,z,w) 4-vector ("Pw"). If the vertex is part of a patch mesh, the position may be used to define a height field. In this case the vertex point contains only a (z) coordinate ("Pz"), and the (x,y)s of points of the height field are set equal to the parametric surface parameters of the mesh.
All primitives have well-defined geometric surface normals, so normals need not be provided with any primitive. The surface normal for a polygon is the perpendicular to the plane containing the polygon. The surface normal for a parametric curved surface is computed by taking the cross product of the surface's parametric derivatives: (dP/du)x(dP/dv). As mentioned in the section Orientation and sides, if the current orientation does not match the orientation of the current coordinate system, normals will be flipped.
The geometric plane normal of a polygon or bilinear patch can be supplied explicitly ("Np"), in which case that normal is used, and the normals are not computed. It is also possible to provide additional shading normals ("N") at polygon and bilinear patch vertices to help make the surface appear smooth.
All primitives have well-defined two-dimensional surface parameters. All the points on the surface of each primitive are functions of these parameters (u,v). Except for NURBS and polygons, the domain of the surface parameters is the unit square from 0 to 1. Texture coordinates may be attached to primitives by assigning four sets of texture coordinates, one set to each corner of this unit square. This is done by setting the current set of texture coordinates or by defining texture coordinates with the geometric primitives as described below.
All geometric primitives normally inherit their color and opacity from the graphics state. However, explicit colors and opacities can be provided when defining the primitive ("Cs" and "Os").
Associated with each geometric primitive definition are additional primitive variables that are passed to their shaders. These variables may define quantities that are constant over the surface (class uniform), or are bilinearly interpolated (class varying). If the primitive variable is uniform, there is one value per surface facet. If the primitive variable is varying, there are four values per surface facet, one for each corner of the unit square in parameter space (except polygons, which are a special case). On parametric primitives (quadrics and patches), varying primitive variables are bilinearly interpolated across the surface of the primitive. Colors, opacities, and shading normals are all examples of varying primitive variables.
The standard predefined primitive variables are defined in Table 5.1, Standard Geometric Primitive Variables. Other primitive variables may be predefined by specific implementations or defined by the user with the RiDeclare function. Primitive variables which are declared to be of type point (including the three predefined position variables) are specified in object space, and will be transformed by the current transformation matrix. If point variables in another space are desired, RiTransformPoints may be used. The two predefined normal variables will be transformed by the equivalent transformation matrix for normal vectors. Primitive variables which are declared to be of type color must contain the correct number of floating point values as defined in RiColorSamples. More information about how to use primitive variables is contained in Part II: The RenderMan Shading Language.
Table 5.1 Standard Geometric Primitive Variables
| Information | Name | Type | Class | Floats |
|---|---|---|---|---|
| Position | "P" "Pz" "Pw" | point point hpoint | vertex vertex vertex | 3 1 4 |
| Normal | "N" "Np" | normal normal | varying uniform | 3 3 |
| Color | "Cs" | color | varying | (3) |
| Opacity | "Os" | color | varying | (3) |
| Texture Coordinates | "s" "t" "st" | float float 2 float | varying varying varying | 1 1 2 |
The RenderMan Interface supports two basic types of polygons: a convex polygon and a general concave polygon with holes. In both cases the polygon must be planar. Collections of polygons can be passed by giving a list of points and an array that indexes these points.
The geometric normal of the polygon is computed by computing the normal of the plane containing the polygon (unless it is explicitly specified). If the current orientation is left-handed, then a polygon whose vertices were specified in clockwise order (from the point of view of the camera) will be a front-facing polygon (that is, will have a normal vector which points toward the camera). If the current orientation is right-handed, then polygons whose vertices were specified in counterclockwise order will be front-facing. The shading normal is set to the geometric normal unless it is explicitly specified at the vertices.
The surface parameters of a polygon are its (x,y) coordinates. This is because the height z of a plane is naturally parameterized by its (x,y) coordinates, unless it is vertical. Texture coordinates are set equal to the surface parameters unless texture coordinates are given explicitly, one set per vertex. Polygons do not inherit texture coordinates from the graphics state.
The rules for primitive variable interpolation and texture coordinates are different for polygons than for all other geometric primitives. Uniform primitive variables are supplied for each polygon. Varying primitive variables are supplied for each polygon vertex, and are interpolated across the interior without regard to the artificial surface parameters defined above. Note that interpolating values across polygons is inherently ill-defined. However, linearly interpolating values across a triangle is always well defined. Thus, for the purposes of interpolation, polygons are always decomposed into triangles. However, the details of how this decomposition is done is implementation-dependent and may depend on the view.
RiPolygon( nvertices, parameterlist ) RtInt nvertices;
nvertices is the number of vertices in a single closed planar convex polygon. parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable which has been defined with RiDeclare. The parameter list must include at least position ("P") information. If a primitive variable is varying, the array contains nvertices elements of the type corresponding to the token. If the variable is uniform, the array contains a single element. The number of floats associated with each type is given in Table 5.1, Standard Geometric Primitive Variables.
No checking is done by the RenderMan Interface to ensure that polygons are planar, convex and nondegenerate. The rendering program will attempt to render invalid polygons but the results are unpredictable.
RIB BINDING Polygon parameterlist
The number of vertices in the polygon is determined implicitly by the number of elements in the required position array.
EXAMPLE
RtPoint points[4] = ( 0.0, 1.0, 0.0, 0.0, 1.0, 1.0,
0.0, 0.0, 1.0, 0.0, 0.0, 0.0);
RiPolygon(4, RI_P, (RtPointer)points, RI_NULL);
SEE ALSO
RiGeneralPolygon, RiPointsGeneralPolygons, RiPointsPolygons
An example of the definition of a “Gouraud-shaded” polygon is:
RtPoint points[4]; RtColor colors[4]; RiPolygon( 4, "P", (RtPointer)points, "Cs", (RtPointer)colors, RI_NULL );
A “Phong-shaded” polygon is given by:
RtPoint points[4]; RtPoint normals[4]; RiPolygon( 4, "P", (RtPointer)points, "N", (RtPointer)normals, RI_NULL );
A “Phong-shaded” polygon with a precomputed plane normal is:
RtPoint points[4]; RtPoint normals[4]; RtPoint plane_normal; RiPolygon( 4, "P", (RtPointer)points, "N", (RtPointer)normals, "Np", (RtPointer)plane_normal, RI_NULL );
RiGeneralPolygon( nloops, nvertices, parameterlist ) RtInt nloops; RtInt nvertices[];
Define a general planar concave polygon with holes. This polygon is specified by giving nloops lists of vertices. The first loop is the outer boundary of the polygon; all additional loops are holes. The array nvertices contains the number of vertices in each loop, and has length nloops. The vertices in all the loops are concatenated into a single vertex array. The length of this array, n, is equal to the sum of all the values in the array nvertices.
parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable that has been defined with RiDeclare. The parameter list must include at least position ("P") information. If a primitive variable is varying, the array contains n elements of the type corresponding to the token. If the variable is uniform, there is a single element of that type. The number of floats associated with each type is given in Table 5.1, Standard Geometric Primitive Variables. The interpretation of these variables is the same as for a convex polygon.
No checking is done by the RenderMan Interface to ensure that polygons are planar and nondegenerate. The rendering program will attempt to render invalid polygons but the results are unpredictable.
RIB BINDING GeneralPolygon nvertices parameterlist
The number of loops in the general polygon is determined implicitly by the length of the nvertices array.
EXAMPLE GeneralPolygon [4 3] "P" [ 0 0 0 0 1 0 0 1 1 0 0 1 0 0.25 0.5 0 0.75 0.75 0 0.75 0.25 ] SEE ALSO RiPolygon, RiPointsPolygons, RiPointsGeneralPolygons
RiPointsPolygons( npolys, nvertices, vertices, parameterlist )< RtInt npolys;< RtInt nvertices[]; RtInt vertices[];
Define npolys planar convex polygons that share vertices. The array nvertices contains the number of vertices in each polygon and has length npolys. The array vertices contains, for each polygon vertex, an index into the varying primitive variable arrays. The varying arrays are 0-based. vertices has length equal to the sum of all of the values in the nvertices array. Individual vertices in the parameterlist are thus accessed indirectly through the indices in the array vertices.
parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable that has been defined with RiDeclare. The parameter list must include at least position ("P") information. If a primitive variable is varying, the array contains n elements of the type corresponding to the token, where the number n is equal to the maximum value in the array vertices plus one. If the variable is uniform, the array contains npolys elements of the associated type. The number of floats associated with each type is given in Table 5.1, Standard Geometric Primitive Variables. The interpretation of these variables is the same as for a convex polygon.
No checking is done by the RenderMan Interface to ensure that polygons are planar, convex and nondegenerate. The rendering program will attempt to render invalid polygons but the results are unpredictable.
RIB BINDING PointsPolygons nvertices vertices parameterlist
The number of polygons is determined implicitly by the length of the nvertices array.
EXAMPLE PointsPolygons [3 3 3] [0 3 2 0 1 3 1 4 3] "P" [0 1 1 0 3 1 0 0 0 0 2 0 0 4 0] "Cs" [0 .3 .4 0 .3 .9 .2 .2 .2 .5 .2 0 .9 .8 0] SEE ALSO RiGeneralPolygon, RiPointsGeneralPolygons, RiPolygon
RiPointsGeneralPolygons( npolys, nloops, nvertices, vertices, parameterlist ) RtInt npolys; RtInt nloops[]; RtInt nvertices[]; RtInt vertices[];
Define npolys general planar concave polygons, with holes, that share vertices. The array nloops indicates the number of loops comprising each polygon and has a length npolys. The array nvertices contains the number of vertices in each loop and has a length equal to the sum of all the values in the array nloops. The array vertices contains, for each loop vertex, an index into the varying primitive variable arrays. All of the arrays are 0-based. vertices has a length equal to the sum of all the values in the array nvertices. Individual vertices in the parameterlist are thus accessed indirectly through the indices in the array vertices.
parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable that has been defined with RiDeclare. The parameter list must include at least position ("P") information. If a primitive variable is varying, the array contains n elements of the type corresponding to the token. The number n is equal to the maximum value in the array vertices plus one. If the variable is uniform, the array contains npolys elements of the associated type. The number of floats associated with each type is given in Table 5.1, Standard Geometric Primitive Variables. The interpretation of these variables is the same as for a convex polygon. No checking is done by the RenderMan Interface to ensure that polygons are planar and nondegenerate. The rendering program will attempt to render invalid polygons but the results are unpredictable.
RIB BINDING PointsGeneralPolygons nloops nvertices vertices parameterlist
The number of polygons is determined implicitly by the length of the nloops array.
EXAMPLE PointsGeneralPolygons [2 2] [4 3 4 3] [0 1 4 3 6 7 8 1 2 5 4 9 10 11] "P" [0 0 1 0 1 1 0 2 1 0 0 0 0 1 0 0 2 0 0 0.25 0.5 0 .75 .75 0 .75 .25 0 1.25 0.5 0 1.75 .75 0 1.75 .25] SEE ALSO RiGeneralPolygon, RiPointsPolygons, RiPolygon
Patches can be either uniform or non-uniform (contain different knot values). Patches can also be rational or non-rational depending on whether the control points are (x,y,z) or (x,y,z,w). Patches may also be bilinear or bicubic. The graphics state maintains two 4x4 matrices that define the bicubic patch basis matrices. One of these is the current u-basis and the other is the current v-basis. Basis matrices are used to transform from the power basis to the preferred basis.
RiBasis( ubasis, ustep, vbasis, vstep ) RtBasis ubasis, vbasis; RtInt ustep, vstep;
Set the current u-basis to ubasis and the current v-basis to vbasis. Predefined basis matrices exist for the common types:
RtBasis RiBezierBasis; RtBasis RiBSplineBasis; RtBasis RiCatmullRomBasis; RtBasis RiHermiteBasis; RtBasis RiPowerBasis;
The variables ustep and vstep specify the number of control points that should be skipped in the u and v directions, respectively, to get to the next patch in a bicubic patch mesh. The appropriate step values for the predefined cubic basis matrices are:
| Basis | Step |
|---|---|
| RiBezierBasis | 3 |
| RiBSplineBasis | 1 |
| RiCatmullRomBasis | 1 |
| RiHermiteBasis | 2 |
| RiPowerBasis | 4 |
The default basis matrix is RiBezierBasis in both directions.
RIB BINDING Basis uname ustep vname vstep Basis uname ustep vbasis vstep Basis ubasis ustep vname vstep Basis ubasis ustep vbasis vstep
For each basis, either the name of a predefined basis (as a string) or a matrix may be supplied. If a basis name specified, it must be one of: "bezier", "b-spline", "catmull-rom", "hermite", or "power."
EXAMPLE Basis "b-spline" 1 [-1 3 -3 1 3 -6 3 0 -3 3 0 0 1 0 0 0] 1 SEE ALSO RiPatch, RiPatchMesh
Note that the geometry vector used with the RiHermiteBasis basis matrix must be (point0, vector0, point1, vector1), which is a permutation of the Hermite geometry vector often found in mathematics texts. Using this formulation permits a step value of 2 to correctly increment over data in Hermite patch meshes.
RiPatch( type, parameterlist ) RtToken type;
Define a single patch. type can be either "bilinear" or "bicubic". parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable which has been defined with RiDeclare. The parameter list must include at least position ("P", "Pw" or "Pz") information. Patch arrays are specified such that u varies faster than v.
Four points define a bilinear patch, and 16 define a bicubic patch. The order of vertices for a bilinear patch is (0,0),(1,0),(0,1),(1,1). Note that the order of points defining a quadrilateral is different depending on whether it is a bilinear patch or a polygon. The vertices of a polygon would normally be in clockwise (0,0),(0,1),(1,1),(1,0) order.
Patch primitive variables which are uniform should supply one value, which is constant over the patch. Primitive variables which are varying should supply four values, one for each parametric corner of the patch. The actual size of each array is this number of values times the size of the type associated with the variable.
RIB BINDING Patch type parameterlist EXAMPLE Patch "bilinear" "P" [ -0.08 0.04 0.05 0 0.04 0.05 -0.08 0.03 0.05 0 0.03 0.05] SEE ALSO RiBasis, RiNuPatch, RiPatchMesh
Figure 5.1 Bicubic patch vertex ordering
(click on image to view a larger version)
RiPatchMesh( type, nu, uwrap, nv, vwrap, parameterlist ) RtToken type; RtToken uwrap, vwrap; RtInt nu, nv;
This primitive is a compact way of specifying a quadrilateral mesh of patches. Each individual patch behaves as if it had been specified with RiPatch. type can be either "bilinear" or "bicubic." parameterlist is a list of token-array pairs where each token is one of the geometric primitive variables or a variable which has been defined with RiDeclare. The parameter list must include at least position ("P", "Pw" or "Pz") information. Patch mesh vertex data is supplied in first u and then v order just as for patches. The number of control points in a patch mesh is (nu)*(nv).
Meshes can wrap around in the u or v direction, or in both directions. If meshes wrap, they close upon themselves at the ends and the first control points will be automatically repeated. As many as three control points may be repeated, depending on the basis matrix of the mesh. The way in which meshes wrap is indicated by giving a wrap mode value of either "periodic" or "nonperiodic."
The actual number of patches produced by this request depends on the type of the patch and the wrap modes specified. For bilinear patches, the number of patches in the u direction, nupatches, is given by
while for bicubic patches,
The same rules hold in the v direction. The total number of patches produced is equal to the product of the number of patches in each direction.
If a variable other than position varies, it contains n values, one for each patch corner, where n is defined by:
(with nupatches and nvpatches defined as given above). If a variable is uniform, it contains nupatches*nvpatches elements of its type, one for each patch. (See Figure 5.2)
A patch mesh is parameterized by a (u,v) which goes from 0 to 1 for the entire mesh. Texture maps that are assigned to meshes that wrap should also wrap so that filtering at the seams can be done correctly (see the section on Texture Map Utilities). If texture coordinates are inherited from the graphics state, they correspond to the corners of the mesh.
Height fields can be specified by giving just a z coordinate at each vertex (using "Pz"); the x and y coordinates are set equal to the parametric surface parameters. Height fields cannot be periodic.
RIB BINDING
PatchMesh type nu uwrap nv vwrap parameterlist
EXAMPLE
RtPoint pts[28]
RtFloat foos[2];
RtFloat bars[6];
RiBasis(RiBezierBasis, 3, RiBezierBasis, 3);
RiDeclare("foo", "uniform float");
RiDeclare("bar", "varying float");
RiPatchMesh("bicubic", 7, "nonperiodic", 4, "nonperiodic",
"P", (RtPointer)pts, "foo", (RtPointer)foos,
"bar", (RtPointer)bars, RI_NULL);
SEE ALSO
RiBasis, RiNuPatch, RiPatch
(click on image to view a larger version)
Non-uniform B-spline patches are also supported by the RenderMan Interface. Rational quadratic B-splines provide exact representations of many different surfaces including general quadrics, tori, surfaces of revolution, tabulated cylinders, and ruled surfaces.
RiNuPatch( nu, uorder, uknot, umin, umax, nv, vorder, vknot, vmin, vmax, parameterlist ) RtInt nu, nv; RtInt uorder, vorder; RtFloat uknot[], vknot[]; RtFloat umin, umax, vmin, vmax;
This procedure creates a tensor product rational or polynomial non-uniform B-spline surface patch mesh. parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable that has been defined with RiDeclare. The parameter list must include at least position ("P" or "Pw") information.
The surface specified is rational if the positions of the vertices are 4-vectors (x,y,z,w), and polynomial if the positions are 3-vectors (x,y,z). The number of control points in the u direction equals nu and the number in the v direction equals nv. The total number of vertices is thus equal to (nu)*(nv). The order must be positive and is equal to the degree of the polynomial basis plus 1. There may be different orders in each parametric direction. The number of control points should be at least as large as the order of the polynomial basis. If not, a spline of order equal to the number of control points is computed. The knot vectors associated with each control point (uknot[], vknot[]) must also be specified. Each value in these arrays must be greater than or equal to the previous value. The number of knots is equal to the number of control points plus the order of the spline. The surface is defined in the range umin to umax and vmin to vmax. This is different from other geometric primitives where the parameter values are always assumed to lie between 0 and 1. Each min must be less than its max. min must also be greater than or equal to the corresponding (order-1)th knot value. max must be less than or equal to the nth knot value.
If texture coordinates primitive variables are not present, the current texture coordinates are assigned to corners defined by the rectangle (umin,umax) and (vmin,vmax) in parameter space.
RIB BINDING NuPatch nu uorder uknot umin umax nv vorder vknot vmin vmax parameterlist EXAMPLE NuPatch 9 3 [ 0 0 0 1 1 2 2 3 3 4 4 4 ] 0 4 2 2 [ 0 0 1 1 ] 0 1 "Pw" [ 1 0 0 1 1 1 0 1 0 2 0 2 -1 1 0 1 -1 0 0 1 -1 -1 0 1 0 -2 0 2 1 -1 0 1 1 0 0 1 1 0 -3 1 1 1 -3 1 0 2 -6 2 -1 1 -3 1 -1 0 -3 1 -1 -1 -3 1 0 -2 -6 2 1 -1 -3 1 1 0 -3 1 ] SEE ALSO RiPatch, RiPatchMesh
NURBS may contain holes that are specified by giving a single closed curve in parameter space.
RiTrimCurve( nloops, ncurves, order, knot, min, max, n, u, v, w ) RtInt nloops RtInt ncurves[]; RtInt order[]; RtFloat knot[]; RtFloat min[], max[]; RtInt n[]; RtFloat u[], v[], w[];
Set the current trim curve. The trim curve contains nloops loops, and each of these loops contains ncurves curves. The total number of curves is equal to the sum of all the values in ncurves. Each of the trimming curves is a non-uniform rational B-spline curve in homogeneous parameter space (u,v,w). The curves of a loop connect in head-to-tail fashion and must be explicitly closed. The arrays order, knot, min, max, n, u, v, w contain the parameters describing each trim curve. All the trim curve parameters are concatenated together into single large arrays. The meanings of these parameters are the same as the corresponding meanings for a non-uniform B-spline surface.
Trim curves exclude certain areas from the non-uniform B-spline surface definition. The inside must be specified consistently using two rules: an odd winding rule that states that the inside consists of all regions for which an infinite ray from any point in the region will intersect the trim curve an odd number of times, and a curve orientation rule that states that the inside consists of the regions to the “left” as the curve is traced.
Trim curves are typically used to specify boundary representations of solid models. Since trim curves are approximations and not exact, some artifacts may occur at the boundaries between intersecting output primitives. A more accurate method is to specify solids using spatial set operators or constructive solid geometry (CSG). This is described in the section on Solids and Spatial Set Operations.
If the particular implementation does not support Trim Curves, all trim curves are ignored and the entire NURB surface is always rendered.
RIB BINDING TrimCurve ncurves order knot min max n u v w
The number of loops is determined implicitly by the length of the ncurves array.
EXAMPLE
RtInt nloops = 1;
RtInt ncurves[1] = { 1 };
RtInt order[1] = { 3 };
RtFloat knot[12] = { 0,0,0,1,1,2,2,3,3,4,4,4 };
RtFloat min[1] = { 0 };
RtFloat max[1] = { 4 };
RtInt n[1] = { 9 };
RtFloat u[9] = { 1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0 };
RtFloat v[9] = { 0.5, 1.0, 2.0, 1.0, 0.5, 0.0, 0.0, 0.0, 0.5 };
RtFloat w[9] = { 1.0, 1.0, 2.0, 1.0, 1.0, 1.0, 2.0, 1.0, 1.0 };
RiTrimCurve(nloops, ncurves, order, knot, min, max, n, u, v, w);
SEE ALSO
RiNuPatch, RiSolidBegin
Many common shapes can be modeled with quadrics. Although it is possible to convert quadrics to patches, they are defined as primitives because special-purpose rendering programs render them directly and because their surface parameters are not necessarily preserved if they are converted to patches. Quadric primitives are particularly useful in solid and molecular modeling applications.
All the following quadrics are rotationally symmetric about the z axis (see Figure 5.3). In all the quadrics u and v are assumed to run from 0 to 1. These primitives all define a bounded region on a quadric surface. It is not possible to define infinite quadrics. Note that each quadric is defined relative to the origin of the object coordinate system. To position them at another point or with their symmetry axis in another direction requires the use a modeling transformation. The geometric normal to the surface points “outward” from the z-axis, if the current orientation matches the orientation of the current transformation and "inward" if they don't match. The sense of a quadric can be reversed by giving negative parameters. For example, giving a negative thetamax parameter in any of the following definitions will turn the quadric inside-out.
Each quadric has a parameterlist. This is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable which has been defined with RiDeclare. Position variables should not be given with quadrics. All angular arguments to these functions are given in degrees. The trigonometric functions used in their definitions are assumed to also accept angles in degrees.
RiSphere( radius, zmin, zmax, thetamax, parameterlist ) RtFloat radius; RtFloat zmin, zmax; RtFloat thetamax;
Requests a sphere defined by the following equations:
Note that if zmin > -radius or zmax < radius, the bottom or top of the sphere is open, and that if thetamax is not equal to 360 degrees, the sides are also open.
RIB BINDING Sphere radius zmin zmax thetamax parameterlist Sphere [radius zmin zmax thetamax] parameterlist EXAMPLE RiSphere(0.5, 0.0, 0.5, 360.0, RI_NULL); SEE ALSO RiTorus
RiCone( height, radius, thetamax, parameterlist ) RtFloat height; RtFloat radius; RtFloat thetamax;
Requests a cone defined by the following equations:
Note that the bottom of the cone is open, and if thetamax is not equal to 360 degrees, the sides are open.
RIB BINDING Cone height radius thetamax parameterlist Cone [height radius thetamax] parameterlist EXAMPLE RtColor four_colors[4]; RiCone(0.5, 0.5, 270.0, "Cs", (RtPointer)four_colors, RI_NULL); SEE ALSO RiCylinder, RiDisk, RiHyperboloid
RiCylinder( radius, zmin, zmax, thetamax, parameterlist ) RtFloat radius; RtFloat zmin, zmax; RtFloat thetamax;
Requests a cylinder defined by the following equations:
Note that the cylinder is open at the top and bottom, and if thetamax is not equal to 360 degrees, the sides also are open.
RIB BINDING Cylinder radius zmin zmax thetamax parameterlist Cylinder [radius zmin zmax thetamax] parameterlist EXAMPLE Cylinder .5 .2 1 360 SEE ALSO RiCone, RiHyperboloid
RiHyperboloid( point1, point2, thetamax, parameterlist ) RtPoint point1, point2; RtFloat thetamax;
Requests a hyperboloid defined by the following equations:
assuming that point1 = (x1,y1, z1) and point2 = (x2, y2, z2).
The cone, disk and cylinder are special cases of this surface. Note that the top and bottom of the hyperboloid are open when point1 and point2, respectively, are not on the z-axis. Also, if thetamax is not equal to 360 degrees, the sides are open.
RIB BINDING
Hyperboloid x1 y1 z1 x2 y2 z2 thetamax parameterlist
Hyperboloid [x1 y1 z1 x2 y2 z2 thetamax] parameterlist
EXAMPLE
Hyperboloid 0 0 0 .5 0 0 270 "Cs" [1 1 1 .5 .9 1 .2 .9 0 .5 .2 0]
SEE ALSO
RiCone, RiCylinder, RiDisk
RiParaboloid( rmax, zmin, zmax, thetamax, parameterlist ) RtFloat rmax; RtFloat zmin, zmax; RtFloat thetamax;
Requests a paraboloid defined by the following equations:
Note that the top of the paraboloid is open, and if thetamax is not equal to 360 degrees, the sides are also open.
RIB BINDING Paraboloid rmax zmin zmax thetamax parameterlist Paraboloid [rmax zmin zmax thetamax] parameterlist EXAMPLE Paraboloid .5 .2 .7 270 SEE ALSO RiHyperboloid
RiDisk( height, radius, thetamax, parameterlist ) RtFloat height RtFloat radius; RtFloat thetamax;
Requests a disk defined by the following equations:
Note that the surface normal of the disk points in the positive z direction when thetamax is positive.
RIB BINDING Disk height radius thetamax parameterlist Disk [height radius thetamax] parameterlist EXAMPLE RiDisk(1.0, 0.5, 270.0, RI_NULL); SEE ALSO RiCone, RiHyperboloid
RiTorus( majorradius, minorradius, phimin, phimax, thetamax, parameterlist ) RtFloat majorradius, minorradius; RtFloat phimin, phimax; RtFloat thetamax;
Requests a torus defined by the following equations:
Note that if phimax-phimin or thetamax is not equal to 360 degrees, the torus is open.
RIB BINDING Torus rmajor rminor phimin phimax thetamax parameterlist Torus [rmajor rminor phimin phimax thetamax] parameterlist EXAMPLE Torus 1 .3 60 90 360 SEE ALSO RiSphere
Figure 5.3 Quadric surface primitives
(click on image to view a larger version)
Procedural primitives can be specified as follows:
RiProcedural( data, bound, subdividefunc, freefunc ) RtPointer data; RtBound bound; RtFunc subdividefunc; RtFunc freefunc;
This defines a procedural primitive. The data parameter is a pointer to an opaque data structure that defines the primitive. (The rendering program does not “look inside” data, it simply records it for later use by the procedural primitive.) bound is an array of floats that define the bounding box of the primitive in object space. subdividefunc is the routine that the renderer should call (when necessary) to have the primitive subdivided. A bucket-based rendering scheme can potentially save memory space by delaying this call until the bounding box overlaps a bucket that must be rendered. The calling sequence for subdividefunc is:
(*subdividefunc)( data, detail ) RtPointer data; RtFloat detail;
where data is the parameter that was supplied in defining the primitive, and detail is the screen area of the bound of the primitive. When subdividefunc is called, it is expected to subdivide the primitive into other smaller procedural primitives or into any number of non-procedural primitives. If the renderer can not determine the true detail of the bound (e.g., if the geometric primitive data is being archived to a file), subdividefunc may be called with a detail value equal to RI_INFINITY. This should be interpreted by the subdividefunc as a request for the immediate full generation of the procedura primitive.
freefunc is a procedure that the rendering program calls to free the primitive when the data is no longer needed.. The calling sequence for freefunc is:
(*freefunc)( data ) RtPointer data;
Note that the rendering program may call back multiple times with the same procedural primitive, so the data area should not be overwritten or freed until the freefunc is called.
Additional geometric primitives can be specified using the following procedure.
RiGeometry( type, parameterlist ) RtToken type;
This procedure provides a standard way of defining an implementation-specific geometric primitive. The values supplied in the parameter list for each primitive is implementation specific.
RIB BINDING
Geometry name parameterlist
EXAMPLE
RiGeometry("teapot," RI_NULL);
Solids and Spatial Set Operations
All of the previously described geometric primitives can be used to define a solid by bracketing a collection of surfaces with RiSolidBegin and RiSolidEnd. This is often referred to as the boundary representation of a solid. When specifying a volume it is important that boundary surfaces completely enclose the interior. Normally it will take several surfaces to completely enclose a volume since, except for the sphere, the torus, and potentially a periodic patch or patch mesh, none of the geometric primitives used by the rendering interface completely enclose a volume. A set of surfaces that are closed and non-self-intersecting unambiguously defines a volume. However, the RenderMan Interface performs no explicit checking to ensure that these conditions are met. The inside of the volume is the region or set of regions that have finite volume; the region with infinite volume is considered outside the solid. For consistency the normals of a solid should always point outwards.
RiSolidBegin( operation ) RtToken operation; RiSolidEnd()
RiSolidBegin the definition of a solid. operation may be one of the following tokens: "primitive," "intersection," "union," "difference." Intersection and union operations form the set intersection and union of the specified solids. Difference operations require at least 2 parameter solids and subtract the last n-1 solids from the first (where n is the number of parameter solids).
When the innermost solid block is a "primitive" block, no other RiSolidBegin calls are legal. When the innermost solid block uses any other operation, no geometric primitives are legal.
RiSolidEnd terminates the definition of the solid.
RIB BINDING SolidBegin operation SolidEnd - EXAMPLE SolidBegin "union" SEE ALSO RiInterior, RiTrimCurve
A single solid sphere can be created using
RiSolidBegin( "primitive" ); RiSphere( 1.0, -1.0, 1.0, 360.0, RI_NULL ); RiSolidEnd();
Note that if the same sphere is defined outside of a RiSolidBegin-RiSolidEnd block, it is not treated as a volume-containing solid. A solid hemisphere can be created with
RiSolidBegin( "primitive" );
RiSphere( 1.0, 0.0, 1.0, 360.0, RI_NULL );
RiDisk( 0.0, 1.0, -360.0, RI_NULL );
RiSolidEnd();
(Note that the -360 causes the surface normal of the disk to point towards negative z.)
A composite solid is one formed using spatial set operations. The allowed set operations are "intersection," "union," and "difference." A spatial set operation has n operands, each of which is either a primitive solid defined using RiSolidBegin("primitive")-RiSolidEnd, or a composite solid that is the result of another set operation. For example, a closed cylinder would be subtracted from a sphere as follows:
RiSolidBegin( "difference" ); RiSolidBegin( "primitive" ); RiSphere( 1.0, -1.0, 1.0, 360.0, RI_NULL ); RiSolidEnd(); RiSolidBegin( "primitive" ); RiDisk( 2.0, 0.5, 360.0, RI_NULL ); RiCylinder( 0.5, -2.0, 2.0, 360.0, RI_NULL ); RiDisk( -2.0, 0.5, -360.0, RI_NULL ); RiSolidEnd(); RiSolidEnd();
When performing a difference the sense of the orientation of the surfaces being subtracted is automatically reversed.
Attributes may be changed freely inside solids. Each section of a solid's surface can have a different surface shader and color. For consistency a single solid should have a single interior and exterior volume shader.
If the Solid Modeling optional capability is not supported by a particular implementation, all primitives are rendered as a collection of surfaces, and the spatial set operators are ignored.
A single geometric primitive or a list of geometric primitives (all of the same type) may be retained by enclosing them with RiObjectBegin and RiObjectEnd. The RenderMan Interface allocates and returns an RtObjectHandle for each retained object defined in this way. This handle can subsequently be used to reference the object when creating instances with RiObjectInstance. Objects are not rendered when they are defined within an RiObjectBegin-RiObjectEnd block; only an internal definition is created. All of an object's attributes are inherited at the time it is instanced, not at the time at which it is created.
RtObjectHandle RiObjectBegin() RiObjectEnd()
RiObjectBegin starts the definition of an object and return a handle for later use with RiObjectInstance. If the handle returned is NULL, an object could not be created.
RiObjectEnd ends the definition of the current object.
RIB BINDING ObjectBegin sequencenumber ObjectEnd -
The sequencenumber is a unique object identification number which is provided by the RIB client to the RIB server. Both client and server maintain independent mappings between the sequencenumber and their corresponding RtObject-Handles. If sequencenumber has been used to define a previous object, that object is replaced with the new definition. The number must be in the range 0 to 65535.
EXAMPLE
ObjectBegin 2
Sphere 1 -1 1 360
ObjectEnd
SEE ALSO
RiFrameEnd, RiObjectInstance, RiWorldEnd
RiObjectInstance( handle ); RtObjectHandle handle;
Create an instance of a previously defined object. The object inherits the current set of attributes defined in the graphics state.
RIB BINDING ObjectInstance sequencenumber
The object must have been defined to have a handle sequencenumber with a previous RiObjectBegin.
EXAMPLE
ObjectInstance 2
SEE ALSO
RiFrameEnd, RiObjectBegin, RiWorldEnd
