DRAWP3D FORTRAN LANGUAGE REFERENCE GUIDE

Introduction
Usage
Specifying Colors, Points, and Vectors
Vertex Lists
Predefined Objects
Fortran Parameters Used by the DrawP3D Interface
Functions
Description of functions

Additional DRAWP3D documents:

Introduction

This document gives the details of the Fortran language interface to DrawP3D. It begins with general usage instructions, and includes detailed descriptions of predefined quantities and the function calling interface.

Usage

The Fortran interface to DrawP3D uses a number of constants with special meanings. These constants are defined using PARAMETER statements in the file drawp3d_def.f, which can be included in your code if your Fortran compiler supports file inclusion. If not, you will have to insert the definitions manually or use the parameter values in place of the names. These parameters will be written in upper case; they all begin with P and their values are given elsewhere in this document. In general, when a constant is mentioned in this manual, it will be followed by its value in parenthesis, for example PTRUE (1).

Drawp3d_def.f also provides type statements for the functions of DrawP3D. All are integer-valued functions, returning either PPASS (1) or PFAIL (0) depending on whether the function succeeded or failed for some reason. Unless otherwise specified, all parameters are input only; they are not modified by DrawP3D.

Compile the DrawP3D program as you would any Fortran program, and link it against the DrawP3D object library. On Unix systems this will be done using a switch like -ldrawp3d on the appropriate command; on VMS systems you will need to include drawp3d.olb. These library names are system-dependent, so check to make sure the names are the same at your site.

Specifying Colors, Points, and Vectors

The Fortran interface to DrawP3D often requires the user to specify a color as a real array of dimension 4, or to specify a point or vector as a real array of dimension 3. This is done in the obvious fashion. Consider COLOR, POINT, and VECTOR defined as follows:

	REAL COLOR(4), POINT(3), VECTOR(3)

Then COLOR(1) through (4) will be the red, green, blue, and opacity components of the color respectively, and POINT(1) through POINT(3) or VECTOR(1) through VECTOR(3) will be the X, Y, and Z components of the point or vector respectively.

Vertex Lists

In DrawP3D, a vertex must include a set of 3D coordinates. It can also include a local normal vector and/or either a color or a scalar value to be mapped into a color by the current color map function. Some special functions provide for vertices with two scalar values (and no colors), although most functions will ignore this second value. Considering all these cases, there are seven different possible collections of data for a vertex.

Further, the color information given could be given in several color formalisms. At the moment, the only one supported by DrawP3D is the red-green-blue-opacity color system, but support for others may be added in the future.

This collection of options means that every time a list of vertex data is given, you must specify what data is given for each vertex and what color system is to be used. (Obviously we could have left out the color system selection, but we felt it would be best to leave it in so that codes written now would still work when more options are available). These choices are needed every time you define a geometrical primitive that requires a list of vertices.

Each primitive creation function includes parameters for a vertex type and a color mode. The possible vertex types are PCVX (0) (for coordinate-only vertices), PCCVX (1) (coordinates and colors), PCNVX (3) (coordinates and normals), PCCNVX(2) (coordinates, colors, and normals), PCVVX (4) (coordinates and values to be mapped to colors), PCVNVX (5) (coordinates, values, and normals), and PCVVVX (6) (coordinates and two values). The option for color mode should be specified as PRGB (0), for the red-green-blue-opacity color specification scheme.

In the FORTAN language interface to P3D, functions requiring vertex data are passed three data arrays. If there are N vertices to be defined, the first of these will be a real array of dimension (3,N) containing the X, Y, and Z coordinates of each vertex. This array is generally called 'coords' in the function specifications in this document.

The second array can take three forms, depending on the vertex type the user passes. If the vertex type requires a color, the array will be of dimension (4,N), and each entry will contain a red, a green, a blue, and an opacity value for that vertex. These values are real between 0.0 and 1.0 inclusive, 1.0 being brightest or most opaque. If the vertex type requires single scalar values to be mapped to colors by the current color map function, the array will be of dimension (1,N), and each real entry will be the value for that vertex. If the vertex type requires two scalar values, the array will be of dimension (2,N), and each pair of real entries will be the values for that vertex. The DrawP3D routines know enough to avoid confusing the two. This array is generally called 'colors' in the function specifications.

The third data array provides normal information for each vertex. It is a real array of dimension (3,N), and each entry includes the X, Y, and Z components of that vertex. This array is generally called norms in the function specifications.

Thus, different vertex list types require different data parameters. The correspondence between type and parameters is as follows:

vertex type	coords param		colors param		normals param

PCVX	        real coords(3,N) 	none			none
PCCVX	        real coords(3,N) 	real colors(4,N)	none
PCCNVX	        real coords(3,N) 	real colors(4,N)	real norms(3,N)
PCNVX	        real coords(3,N) 	none			real norms(3,N)
PCVVX	        real coords(3,N) 	real colors(1,N)	none
PCVNVX	        real coords(3,N) 	real colors(1,N)	real norms(3,N)
PCVVVX          real coords(3,N)	real colors(2,N)	none

Note that some vertex types do not require some of this data. For example, vertices of type PCVX do not require either colors or normals. If the DrawP3D routines are called with vertex types which do not require a certain vertex data parameter, that parameter will never be used, so it is safe to substitute something like '0' for it in the parameter list.

Predefined Objects

standard_camera: A camera looking toward the origin from a point 20.0 units up the Z axis, with the up direction lying along the Y axis.
standard_lights: A GOB consisting of a positional light GOB roat the point (0.0, 2.0, 20.0) and a weak ambient light.

Fortran Parameters Used by the DrawP3D Interface

Version numbers:

PPGENV 		1.0	Current version of P3DGen
PDP3DV 		1.0	Current version of DrawP3D

Return codes:

PPASS 		1	Function status return code
PFAIL 		0	Function status return code

Booleans:

PTRUE 		1	Boolean
PFALSE 		0	Boolean

Vertex types:

PCVX 		0	Vertices are coordinate only	
PCCVX 		1	Vertices have coordinate, color
PCCNVX 		2	Vertices have coordinate, color, normal
PCNVX 		3	Vertices have coordinate, normal
PCVVX 		4	Vertices have coordinate, value
PCVNVX 		5	Vertices have coordinate, value, normal
PCVVVX		6	Vertices have coordinates, two values

Color modes:

PRGB 		0	Color information is RGBA

Predefined materials:

PDFMAT		0	Default material (renderer dependent)
PDULL		1	Dull material (e.g. paper)
PSHINY		2	Shiny material (e.g. plastic, ceramic)
PMETAL		3	Metallic material (e.g. chrome)
PMATTE		4	Matte material (no reflection, e.g. soot)
PALUM		5	Aluminum material (less shiny than chrome)

Symbol name length:

PNAMELN 	64	Maximum length of names of objects

Functions

DrawP3D's FORTRAN function names are lower case and begin with p. These functions must be declared as integers in your FORTRAN programs. We apologize for the inconvenience, but the letters between I and N are taken by other subroutine libraries.

All DrawP3D FORTRAN routines are integer-valued functions, returning either 1 (PPASS) or 0 (PFAIL), depending on whether the function succeeded or failed.

GOB routines:: pchild; pclose; pcyl; pfree; popen; pprtgb
Primitive routines:: pbezp; pmesh; pplygn; pplyln; pplymk; psphr; ptext; ptorus; ptrist
Composite GOB routines:: paxis; pbndbx; piriso; pirzsf; pisosf; prniso; prnzsf; pzsurf
Attribute routines:: pbkcul; pblatt; pclatt; pfatt; pgbclr; pgbmat; piatt; pmtatt; pptatt; pstatt; ptxtht; ptratt; pvcatt
Color map routines:: pstcmp; psdcmp
Transformation routines:: pascal; protat; pscale; ptnsfm; ptrans
Camera routines:: pcamra; pcmbkg; pprtcm
Light source routines:: pamblt; plight
Renderer routines:: pclsrn; pintrn; popnrn; pprtrn; pshtrn; psnap
Debugging routines:: pdebug
Shutdown routines:: pshtdn

Description of functions (in alphabetical order)

pamblt

Purpose:

Create an ambient light primitive GOB

Use:

pamblt( ctype, color );

Parameters:

ctype: integer color type (currently must be PRGB (0))

color: real array(4) containing color components

Discussion:

This function adds an ambient light source to the current GOB. The opacity component of the input color is ignored.

pascal

Purpose:

Add an anisotropic scaling transformation to the current GOB

Use:

pascal( xscale, yscale, zscale );

Parameters:

xscale: real scaling factor in the current GOB's X direction

yscale: real scaling factor in the current GOB's Y direction

zscale: real scaling factor in the current GOB's Z direction

Discussion:

This function adds an anisotropic scaling transformation to the current GOB. This transformation will be concatenated with the existing transformation by left multiplication; GOBs with no existing transformation effectively have the identity transformation associated with them. To add a scaling transformation which is uniform in all directions, see pscale.

paxis

Purpose:

Add an axis gob to the current GOB

Use:

paxis( strt, end, up, strtvl, endvl, ntics, lbl, txtsz, precsn );

Parameters:

strt: real array(3) point where axis starts

end: real array(3) point where axis ends

up: real array(3) up direction of text

strtvl: real value to be placed at start

endvl: real value to be placed at end

ntics: integer value for the number of tics to be displayed. Includes end and start

lbl: character string to be placed below startval

txtsz: real value which gives the size of the text

precsn: integer value for the number of decimal points to be displayed (0..8)

Discussion:

This function adds an axis to the Current GOB. The axis itself is in the (end-start) direction with the tics in the negative (up) direction. The front of the axis is the cross product of (end-start) and (up). Startval is placed at start and endval placed at end. Other values are interpolated and placed at the corresponding tics. The number of tics is specified, and this number includes the end and start tic. If num_tics is less than 2, it is set to 2 by default. The label is placed below startval. All text is scaled by text_size, which is exactly the same as in ptxtht(). The variable precision defines the number of decimal places to be displayed. This range is between 0 and 8, and if the range is exceeded, then precision is set to the nearest number that is within the range.

pbezp

Purpose:

Create a nameless Bezier Patch primitive GOB

Use:

pbezp( vtxtyp, ctype, coords, colors, norms );

Parameters:

vtxtyp: integer vertex type specifier constant

ctype: integer color type (currently only P3D_RGB)

coords: real array of coordinate data (16 vertices)

colors: real array of color data

norms: real array of normal data

Discussion:

This produces a simple bicubic Bezier patch, with a four by four pattern of knots specified by the data given by the 16 vertices. See the section on vertex lists in this document for format information. The use of coloring information on the inner four vertices is renderer dependent.

pbkcul

Purpose:

Add a backface culling attribute to the current GOB

Use:

pbkcul( flag );

Parameters:

flag: integer; turns backface culling on if non-zero, off if zero

Discussion:

Backface culling is a useful feature to save time by not drawing hidden faces of closed objects. It causes surfaces facing away from the not to be drawn. See the description of the various primitives in the User's Guide for information on which surface is the front of any given primitive. This function adds the this attribute to the currently open GOB, where it will apply to that GOB and any of its descendents.

pblatt

Purpose:

Add an arbitrary boolean-valued attribute to the current GOB

Use:

pblatt( attrib, flag );

Parameters:

attrib: character string specifying the attribute name

flag: integer value of the attribute; non-zero means true

Discussion:

This procedure can be used to add an arbitrary boolean attribute to a GOB.

pbndbx

Purpose:

Create a nameless Bounding Box primitive GOB

Use:

pbndbx( crna, crnb );

Parameters:

crna: real array(3) specifies one of the bounding box corners.

crnb: real array(3) specifies the other bounding box corner.

Discussion:

This procedure produces a bounding box. The two corners specify opposite corners on the bounding box diagonal.

pcamra

Purpose:

Create a camera object

Use:

pcamra( name, lookfm, lookat, up, fovea, hither, yon );

Parameters:

lookfm: real array(3) giving the location for the camera

lookat: real array(3) giving the location at which to point the camera

up: real array(3) giving the vector specifying the rotational position of the camera about the line from lookfm to lookat

fovea: real giving the opening angle of the view in degrees

hither: negative real distance to the near clipping plane

yon: negative real distance to the far clipping plane

Discussion:

This procedure creates a camera object, which can be used to specify a view of a model. See the discussion of cameras in the DrawP3D User's Guide for details. Note that the hither and yon values are negative numbers, with the magnitude of hither less than that of yon. Those objects which fall within a cone of opening angle fovea with its base at lookfrom and centered on lookat, and which fall between the hither and yon distances, will be rendered by a psnap function using this camera.

pchild

Purpose:

Add a child GOB to the current GOB.

Use:

pchild( name );

Parameters:

Discussion:

This function causes a previously defined GOB to become a child of the current GOB. Note that it can also be a child of one or more other GOBs, and that it can (and will) have children of its own.

pclatt

Purpose:

Add an arbitrary color-valued attribute to the current GOB.

Use:

pclatt( name, ctype, r, g, b, a );

Parameters:

ctype: integer color type (currently must be PRGB (0))

r: real red color intensity

g: real green color intensity

b: real blue color intensity

a: real color opacity

Discussion:

This procedure can be used to add an arbitrary color attribute to a GOB. Do not confuse this with setting the color of the GOB, which is done with the function pgbclr and involves setting the color attribute named 'color'.

pclose

Purpose:

Close the current GOB.

Use:

pclose();

Parameters: none

Discussion:

This function closes the current GOB. If the current GOB is a child of another open GOB, for example if it was opened by calling popen with an empty character string for a name, the parent open GOB becomes the current GOB. If the current GOB was opened by calling popen with a non-empty name, it must be the highest level open GOB. In this case when the GOB is closed there will be no current GOB until the next call to popen.

pclsrn

Purpose:

Close a renderer.

Use:

pclsrn( name );

Parameters:

Discussion:

This function closes the named renderer. It stays closed until reopened with a call to popnrn. While the renderer is closed, it is not informed of snap functions, the creation of new GOBs or attributes, or anything else; as far as the renderer is concerned absolutely nothing happens while it is closed. This means that it is an error to, for example, define a GOB while the renderer is closed and then open the renderer and attempt to render the GOB.

pcmbkg

Purpose:

Set the background color of a camera object.

Use:

pcmbkg( name, ctype, color );

Parameters:

ctype: integer color type (currently must be PRGB (0))

color: real array(4) containing color components

Discussion:

This function changes the background color of a camera. All scenes subsequently rendered with the changed camera will have backgrounds of the given color, unless and until the background color is changed again. Cameras are created with a black background color.

pcyl

Purpose:

Add a cylinder primitive to the current GOB.

Use:

pcyl();

Parameters: none

Discussion:

This procedure adds a cylinder primitive to the current GOB. The cylinder is of radius 1.0, and extends from the origin to the point (0.0, 0.0, 1.0). It is expected that the user will apply a transformation to it to produce a cylinder of the desired shape in the desired location.

pdebug

Purpose:

Toggle the debugging trace on and off.

Use:

pdebug();

Parameters: none

Discussion:

DrawP3D can produce a debugging trace of its internal operation. The trace is written to the standard error output; it can be very verbose but can be useful for debugging and bug reporting. If no trace is being produced pdebug turns it on; if it is on pdebug turns it off.

pfatt

Purpose:

Add an arbitrary floating point attribute to the current GOB.

Use:

pfatt( name, value );

Parameters:

value: real value to be associated with name

Discussion:

This procedure can be used to add an arbitrary floating point attribute to a GOB.

pfree

Purpose:

Free a named GOB.

Use:

pfree( name );

Parameters:

Discussion:

This function explicitly removes the name from a named GOB. If this GOB is not the descendent of another named GOB, it will be freed, and all of its descendents which do not have names and are not descendents of named GOBs will also be freed. The effect of this mechanism is that a GOB is freed as soon as it becomes impossible to refer to it or any of its ancestors. Note that using popen to create a new gob with the same name as an existing GOB has the effect of applying pfree to the existing GOB.

pgbclr

Purpose:

Specify the gob color attribute of the current GOB.

Use:

pgbclr( ctype, r, g, b, a );

Parameters:

ctype: integer color type (currently must be PRGB (0))

r: real red color intensity

g: real green color intensity

b: real blue color intensity

a: real color opacity

Discussion:

This procedure can be used to set the gob color attribute of a GOB. This call is equivalent to calling pclatt with the attribute name 'color' and the same color parameter.

pgbmat

Purpose:

Specify the gob material attribute of the current GOB.

Use:

pgbmat( material );

Parameters:

material: integer ID of material

Discussion:

This procedure can be used to set the gob material attribute of a GOB. This call is equivalent to calling pmtatt with the attribute name 'material' and the same material parameter. The material ID must be one of the predefined materials, described earlier in this document.

piatt

Purpose:

Add an arbitrary integer-valued attribute to the current GOB.

Use:

piatt( name, value );

Parameters:

value: integer value to be associated with name

Discussion:

This procedure can be used to add an arbitrary integer attribute to a GOB.

pintrn

Purpose:

Create, initialize and open a renderer.

Use:

pintrn( name, rndrer, device, data );

Parameters:

rndrer: character string identifying the renderer

device: character string specifying output device to use (renderer-dependent meaning)

data: character string specifying renderer data string (renderer-dependent meaning)

Discussion:

This function creates, initializes, and opens a renderer. Some possible renderer types are P3D, Painter, Xpainter, GL, PVM, Open Inventor, and VRML.

piriso

Purpose:

Create an iso-valued surface composite GOB from non-Cartesian gridded data, for example data in spherical coordinates.

Use:

piriso( int vtxtyp, data, vdata, nx, ny, nz, value, crdfun, inside );

Parameters:

vtxtyp: integer vertex type to generate

data: 3D real array of data, of dimensions (nx,ny,nz)

vdata: 3D real array of value data for coloring, of dimensions (nx,ny,nz)

nx, ny, nz: integer dimensions of data and valdata

value: real value of the isosurface to extract

crdfun: a subroutine used to map coordinate indices to X-Y-Z (Cartesian) coordinates

inside: integer flag to control whether inner or outer surfaces are drawn

Discussion:

The irregular isosurface composite function is used to extract a surface of constant value from a three dimensional array of real data. The best way to understand what this means is to think of a continuous function in three dimensional space. Consider all the points in space for which the function has a given value. Because the function is continuous, the points must group together to form two dimensional closed surfaces in space. These surfaces are iso-valued surfaces, or isosurfaces, of the continuous function.

The isosurface function assumes that the grid of data that it is passed represents samples of a continuous function in space, and extracts the isosurface of that function at a given function value. Linear interpolation of the data is used to calculate values between grid points. The surfaces formed are closed unless they intersect the boundary of the grid; in that case the parts of the surface that would fall outside are omitted and holes are left in the surface.

The data parameter and its nx, ny, and nz dimensions provide the data for the 3D grid. The subroutine crdfun establishes the relationship between indices within that grid and X-Y-Z (Cartesian) coordinates. It should be defined as follows:

	subroutine crdfun( x, y, z, i, j, k )
	integer i, j, k
	real x, y, z

The function will be called with i, j, and k being integers in the range of 1 to nx, 1 to ny, and 1 to nz respectively. When called from Fortran, piriso assumes the grid data arrays to be in Fortran array order and accesses the array as data(i,j,k).

The value parameter provides the constant value of the isosurface. The inside parameter controls whether inner or outer surfaces are drawn. The outer surface is that for which function values above the surface value lie inside the surface; inner surfaces are drawn such that higher function values lie outside. The distinction controls which direction the 'front' sides of the polygons of the surface are facing.

The two remaining parameters, vtxtype and valdata, control the appearance of the surface. This routine does not support the generation of normals based on gradient direction, so vertex types including normals are mapped to the most similar vertex type not including normals. Most P3D renderers will generate normals based on polygon facing direction later in the rendering process. The supported vertex types are PCVX and PCVVX. For the PCVVX type, the vdata parameter provides value data which is interpolated to the isosurface and used to color the surface according to the current color map.

See the documentation for pisosf for information on the algorithm used to extract the isosurface and other comments.

pirzsf

Purpose:

Create a Z surface composite GOB from non-Cartesian gridded data, for example from polar coordinates.

Use:

pirzsf( vtxtyp, zdata, vdata, nx, ny, crdfun, tstflg, tstfun );

Parameters:

vtxtyp: integer vertex type to generate

zdata: an nx by ny array of floats specifying z values

vdata: an nx by ny array of floats specifying values for coloring via the current color map

nx, ny: dimensions of zdata and vdata

crdfun: a subroutine used to map coordinate indices to X-Y (Cartesian) coordinates

tstflg: integer flag set to non-zero if tstfun is provided

tstfun: a subroutine that excludes points from the Z surface.

Discussion:

This function draws a surface, the height of which is given by the data in the array zdata. Nx and ny specify the dimensions of the zdata and vdata (if present) arrays. When called from Fortran, these data arrays are accessed in Fortran order, as zdata(i,j).

The subroutine crdfun is used to map vertex indices to X-Y (Cartesian) coordinates. It should be defined as follows:

	subroutine crdfun( x, y, i, j )
	real x, y
	integer i, j

The function will be called with i and j ranging from 1 to nx and from 1 to ny respectively, and should set x and y to equal the X and Y (Cartesian) coordinates of the given data point. Thus crdfun serves to define the domain of the Z surface, while zdata serves to define the range.

The parameter vtxtyp specifies the vertex type to be used. Supported vertex types are PCVX and PCVVX. For PCVVX, the user must supply a non-null array vdata. The values in this array will be mapped via the current color map to provide coloring for the surface vertices.

tstfun is an optional user supplied subroutine that determines whether a point should be excluded from the zsurface. If it is not provided tstflg should be set to zero. If it is provided, tstflg should be non-zero and tstfun should be defined as follows:

	subroutine tstfun( ixclde, value, i, j )
	integer ixclde, i, j
	real value

This function is called for each point in the surface, with value set to the z value at that point and i and j to the array indices (between 1 and nx and 1 and ny respectively) of the point in question. If on return from the function ixclde is PTRUE (1), the point will be excluded and a hole will be left in the surface at the appropriate point. If ixclde is PFALSE (0), the point will be included. This enables the user to remove points on the basis of position or value.

pisosf

Purpose:

Create an iso-valued surface composite GOB

Use:

pisosf( vtxtyp, data, vdata, nx, ny, nz, value, crnr1, crnr2, inside );

Parameters:

vtxtyp: integer vertex type to generate

data: 3D real array of data, of dimensions (nx,ny,nz)

valdata: 3D real array of value data for coloring, of dimensions (nx,ny,nz)

nx, ny, nz: integer dimensions of data and valdata

value: real value of the isosurface to extract

crnr1: real array(3) specifying one corner of the volume in which to draw the surface

crnr2: real array(3) specifying the other corner

inside: integer flag to control whether inner or outer surfaces are drawn

Discussion:

The isosurface composite function is used to extract a surface of constant value from a three dimensional array of real data. The best way to understand what this means is to think of a continuous function in three dimensional space. Consider all the points in space for which the function has a given value. Because the function is continuous, the points must group together to form two dimensional closed surfaces in space. These surfaces are iso-valued surfaces, or isosurfaces, of the continuous function.

pisosf assumes that the grid of data that it is passed forms samples of a continuous function in space, and extracts the isosurface of that function at a given function value. Linear interpolation of the data is used to calculate values between grid points. The surfaces formed are closed unless they intersect the boundary of the grid; in that case the parts of the surface that would fall outside are omitted and holes are left in the surface.

The data parameter and its nx, ny, and nz dimensions provide the data for the 3D grid, which is assumed to fill the space defined by the opposite corners corner1 and corner2. The value parameter provides the constant value of the isosurface.

The inside parameter controls whether inner or outer surfaces are drawn. The outer surface is that for which function values above the surface value lie inside the surface; inner surfaces are drawn such that higher function values lie outside. The distinction controls which direction the 'front' sides of the polygons of the surface are facing.

The two remaining parameters, vtxtyp and vdata, control the appearance of the surface. If the vertex type is one which includes normal vectors, normals will be generated; this makes the surface look smoother but substantially increases the memory and file size of the model and takes time to compute. If a vertex type requiring value information is given, the grid of value data is accessed at appropriate points (using linear interpolation as necessary), and the current color map is used to color the surface appropriately. Vertex types implying that explicit colors are to be given for the vertices are converted to the most similar type without explicit colors.

The algorithm used is Lorensen and Cline's Marching Cubes algorithm, as described in the proceedings of Siggraph '87, with several corrections. See the source code for details.

See the routine pbndbx for an easy way to show the boundaries of the volume from which the surface is being extracted.

This routine involves the correct handling of a large number of distinct cases. We believe that all the cases are properly coded, but errors may exist. If you encounter a case where the algorithm seems to create an incorrect surface, particularly one with missing triangles or holes not at the boundary of the volume specified by the corners, please let us know so that we can make the appropriate corrections.

plight

Purpose:

Create a positional light source primitive GOB

Use:

plight( loc, ctype, color );

Parameters:

loc: real array (3) giving the position of the light source.

ctype: integer color type (currently must be PRGB (0))

color: real array(4) giving the color for the light source.

Discussion:

This procedure is used to add a positional light source primitive to the currently open GOB. The opacity component of the input color is ignored. The renderer may retreat the light source to infinity, or otherwise neglect some of the light source data.

pmesh

Purpose:

This function adds a generalized mesh geometrical primitive to the current GOB.

Use:

pmesh( vtxtyp, ctype, npts, coords, colors, norms, nfacet, faclng, vrtind );

Parameters:

vtxtyp: integer vertex type

ctype: integer color type (currently must be PRGB (0))

npts: integer number of vertices

coords: real array of coordinate data

colors: real array of color data

norms: real array of normal data

nfacet: integer number of facets

faclng: integer array of facet length data

vrtind: integer array of facet vertex index data (numbered from 0)

Discussion:

The general mesh is one of the most useful primitives, but also one of the more complex. It consists of a collection of polygonal facets, sharing a common collection of vertices. The first five parameters to pmesh define the vertices (in the usual fashion- see the section on vertex lists in this document), while the remainder of the parameters define how they are grouped to form the facets.

If there are nfacet facets, faclng must be an array of length nfacets containing the number of vertices in each facet. vrtind must be an array of total length equal to the sum of the values in faclng, containing indices into the array of vertices specified by vdata. The first element of facet_lengths specifies a number of entries to be taken from facet_vertices to define the first facet, the second element specifies the number of entries to define the second facet, and so on. NOTE: Vertex indices in vrtind number the vertices from 0, as is the C language custom, rather than from 1, as is the Fortran custom. The front faces of the facets are defined by the right hand rule applied to the vertices in the order in which their indices appear in facet_vertices. This means that the facets of a smooth surface do not necessarily all have their front faces on the same side of the surface.

pmtatt

Purpose:

Add a material-valued attribute to the current GOB.

Use:

pmtatt( name, material );

Parameters:

material: integer ID of material

Discussion:

This procedure can be used to add an arbitrary material attribute to a GOB. Do not confuse this with setting the material of the GOB, which is done with the function pgbmat and involves setting the material attribute named 'material'. The material ID must be one of the predefined materials, described earlier in this document.

popen

Purpose:

Create and open a new named or unnamed GOB.

Use:

popen( name );

Parameters:

Discussion:

All non-primitive GOBs are created and opened using popen and closed using pclose. If popen is called with a non-empty name, a named GOB is created. This can only happen if no GOB is currently open. If popen is called with an empty character string ('') or a character string containing only a single space (' ') as a parameter, a nameless GOB is created. This can only happen if another GOB is already open; the new GOB becomes a child of the previously open GOB.

popnrn

Purpose:

Open a previously closed renderer.

Use:

popnrn( name );

Parameters:

Discussion:

This routine opens a renderer previously closed using dclsrn. It is not necessary to open a renderer immediately after it is created by pinirn, since renderers are created open. Note that any definitions, attributes, snaps, or other changes are ignored by the renderer while it is closed. Thus it is an error to define a GOB while a renderer is closed, open the renderer, and then attempt to render that GOB.

pplygn

Purpose:

Add a polygon geometrical primitive to the current GOB.

Use:

pplygn( vtxtyp, ctype, npts, coords, colors, norms );

Parameters:

vtxtyp: integer vertex type specifier

ctype: integer color type (currently must be PRGB)

npts: integer number of vertices

coords: real array of coordinate data

colors: real array of color data

norms: real array of normal data

Discussion:

This function adds a polygon bounded by the given vertices to the current GOB. See the vertex list section of this document for a description of the vertex data format. It is the user's responsibility to make sure that the vertices given are coplanar. The handling of concave polygons is renderer-dependent. The handling of self-intersecting polygons is very renderer-dependent and should be avoided if at all possible. The front face of the polygon is determined by applying the right hand rule to the circulation direction of the vertices.

pplyln

Purpose:

Add a polyline geometrical primitive to the current GOB.

Use:

pplyln( vtxtyp, ctype, npts, coords, colors );

Parameters:

vtxtyp: integer vertex type specifier

ctype: integer color type (currently must be PRGB)

npts: integer number of vertices

coords: real array of coordinate data

colors: real array of color data

Discussion:

This function adds a polyline defined by the given vertices to the current GOB. See the vertex list section of this document for a description of the vertex data format. Since normal vectors are not applicable to the drawing of polylines, they are not included in the parameter list. Vertex types including normals are converted to the otherwise similar type without normals.

pplymk

Purpose:

Add a polymarker geometrical primitive to the current GOB.

Use:

pplymk( vtxtyp, ctype, npts, coords, colors );

Parameters:

vtxtyp: integer vertex type specifier

ctype: integer color type (currently must be PRGB)

npts: integer number of vertices

coords: real array of coordinate data

colors: real array of color data

Discussion:

This function adds a polymarker defined by the given vertices to the current GOB. See the vertex list section of this document for a description of the vertex data format. At the moment, DrawP3D only supports point markers. Since normal vectors are not applicable to the drawing of polylines, they are not included in the parameter list. Vertex types including normals are converted to the otherwise similar type without normals.

pprtcm

Purpose:

Write a description of a camera to the standard output.

Use:

pprtcm( name );

Parameters:

Discussion:

This routine causes a description of the given camera, including all internal parameters, to be written to the standard output. This can be very useful for debugging purposes.

pprtgb

Purpose:

Write a description of a GOB to the standard output.

Use:

pprtgb( name );

Parameters:

Discussion:

This routine causes a hierarchical description of the given GOB to be written to the standard output. This description includes all of the GOB's attributes, its transformation if any, and all of its children recursively, down to and including any primitive GOBs. This can be very useful for debugging purposes.

pprtrn

Purpose:

Write a description of a renderer to the standard output.

Use:

pprtrn( name );

Parameters:

Discussion:

This routine causes a description of the given renderer, including output file and parameter information, to be written to the standard output. This can be very useful for debugging purposes.

pptatt

Purpose:

Add an arbitrary point-valued attribute to the current GOB.

Use:

pptatt( name, x, y, z );

Parameters:

x: real x coordinate of the point

y: real y coordinate of the point

z: real z coordinate of the point

Discussion:

This procedure can be used to add an arbitrary point attribute to a GOB.

prniso

Purpose:

Create an iso-valued surface composite GOB from randomly distributed data.

Use:

prniso( vtxtyp, ctype, npts, coords, vals, norms, value, inside );

Parameters:

vtxtyp: integer vertex type specifier

ctype: integer color type (currently must be PRGB)

npts: integer number of vertices

coords: real array of coordinate data

vals: real array of value data (as for vertex list 'colors')

norms: real array of normal data

value: real value at which the isosurface is to be drawn

inside: integer flag to control whether inner or outer surfaces are drawn

Discussion:

The random isosurface composite function is used to extract a surface of constant value from a collection of data points in 3D space. The data may be (and in fact should be) ungridded; it need not be defined on a regular array.

The best way to understand isosurfaces is to think of a continuous function in three dimensional space. Consider all the points in space for which the function has a given value. Because the function is continuous, the points must group together to form two dimensional closed surfaces in space. These surfaces are iso-valued surfaces, or isosurfaces, of the continuous function. The data points given provide function values at various points within the space. The random isosurface utility finds a function which has the given values at the given points and is linearly interpolated between them, and extracts an isosurface of that function. The surfaces formed are closed unless they intersect the convex hull of the given data; in that case the parts of the surface that would fall outside are omitted and holes are left in the surface.

The data values are provided to the function in the form of a vertex list. Each point must have three coordinates, and a value to provide the local value of the function defining the isosurface. It is also possible to specify a second value. In this case, the second value will be used to color the surface according to the current color map. Normals may also be provided and will be interpolated, but this is not a very sensible thing to do unless the normals are known to be perpendicular to the surface which is generated. (This will be the case if the normals given correspond to the gradient of the function in question). These combinations of possible vertex quantities mean that the valid vertex types are PCVVX, PCVVVX, and PCVNVX.

The isosurface is generated by first finding the Dirichlet and Delaunay tesselations of the data points, and then using the Delaunay tesselation to define a lattice of tetrahedra, the vertices of which are the given data points. A 'Marching Tets' algorithm is applied to these tetrahedra to extract the isosurface. Value data for coloring or interpolated normal data are calculated by linear interpolation along the edges of the tetrahedra as needed. Note that the result is unique; there are no hidden free parameters the adjustment of which might produce a different isosurface from the same data.

The algorithm used to calculate the Dirichlet and Delaunay structures if that of A. Bowyer (see The Computer Journal, vol. 24, no. 2, 1981). The process is very compute intensive and uses a great deal of memory; generating isosurfaces for large numbers of data points is a very memory-intensive and time-consuming task. Thus it is much better to use pisosf or piriso if at all possible.

prnzsf

Purpose:

Create a Z surface composite GOB from randomly distributed data

Use:

prnzsf( vtxtyp, ctype, npts, coords, colors, norms, tfnull, tfun );

Parameters:

vtxtyp: integer vertex type specifier constant

ctype: integer color type (currently only P3D_RGB)

coords: real array of coordinate data

colors: real array of color data

norms: real array of normal data

tfnull: integer: if PTRUE, then include all points

tfun: a subroutine that excludes points from the Z surface.

Discussion:

This function connects the given data points to form a surface. The given points must form a continuous, single-valued surface in z as a function of x and y. The surface drawn is bounded in the x-y plane by the convex hull of the data points. All vertex types are supported; normal, color, or value data associated with the vertices is used to properly color or light the surface created. For example, vertices of type P3D_CVVTX could be used to color the surface according to a function different from its height.

The user can cause points to be excluded from the surface by setting tfnull to PFALSE (0), and specifying a subroutine tfun to be used in determining which points to exclude. If tfnull is PTRUE (1), all points will be included in the surface and the parameter tfun will be ignored. Excluding a point causes a hole to appear in the surface where the point would have been.

Tfun is a user supplied subroutine that determines whether a point should be excluded from the zsurface. It should be defined as follows:

	subroutine tfun( ixclde, x, y, z, index )
	integer ixclude, index
	real x, y, z

This function is called several times for each point in the data, with the x, y, and z parameters being passed the coordinates of the data point and the index being passed the ordinal index of the given point in the data. NOTE THAT THE INDICES ARE NUMBERED FROM 0, rather than from 1 as would be traditional in Fortran. If on return from the function ixclde is PTRUE (1), the point will be excluded and a hole will be left in the surface at the appropriate point. If ixclde is PFALSE (0), the point will be included. This enables the user to remove points on the basis of position or value.

The connections between points which define the surface are found by calculating the Dirichlet tesselation of the points. This process divides the space in the x-y plane into regions closest to each of the given points. These regions are polygons; the collection of polygons is the Dirichlet tesselation. The dual to this set of polygons is a collection of triangles which have the given data points as their vertices. These triangles make up the Delaunay triangulation of the data and are what is actually drawn to create the Z surface. The convex hull of the data is automatically calculated during the generation of the Delaunay triangulation. The triangulation calculated is completely unambiguous; no hidden free parameters are used to choose which data points are connected to which.

The algorithm used to calculate the Dirichlet and Delaunay structures if that of A. Bowyer (see The Computer Journal, vol. 24, no. 2, 1981). The process is very compute intensive and uses a great deal of memory; generating Z surfaces for large numbers of data points is a very memory-intensive and time-consuming task. Thus it is much better to use pzsurf pirzsf if at all possible.

protat

Purpose:

Add a rotation transformation to the current GOB.

Use:

protat( x, y, z, angle );

Parameters:

x: real x component of axis of rotation

y: real y component of axis of rotation

z: real z component of axis of rotation

angle: angle to rotate, in degrees

Discussion:

This function adds a rotation transformation to the current GOB. This transformation will be concatenated with the existing transformation by left multiplication; GOBs with no existing transformation effectively have the identity transformation associated with them. The positive direction of rotation is determined by the right hand rule.

pscale

Purpose:

Add a scaling transformation to the current GOB.

Use:

pscale( factor );

Parameters:

factor: real factor by which to scale the GOB

Discussion:

This function adds a scaling transformation to the current GOB. This transformation will be concatenated with the existing transformation by left multiplication; GOBs with no existing transformation effectively have the identity transformation associated with them. Values of scale greater than 1.0 enlarge the GOB; values less than 1.0 reduce it. pscale adds a scaling transformation which is uniform in all directions; to add an anisotropic scaling transformation see pascal.

psdcmp

Purpose:

Set the current color map to one of several standard functions.

Use:

psdcmp( min, max, which );

Parameters:

min: real value to be mapped to 0.0

max: real value to be mapped to 1.0

which: integer selector for the standard map function desired

Discussion:

When vertex lists of types containing scalar values (for example, PCVVX (4)) are rendered, the values are translated to colors by the current color map function. psdcmp allows the user to easily select that function.

When translation occurs, the value is first rescaled into the interval from 0.0 to 1.0. If the value is beyond the range delimited by min and max, it maps to 0.0 if it is closer to min or 1.0 if it is closer to max. Otherwise, it maps to (value-min)/(max-min), which is in the range 0.0 to 1.0 inclusive. The mapped value is then passed to the a mapping function. whichmap selects which of the mapping functions will be used, from the following list:

	whichmap	mapping function

	   0	    gray scale, 0.0 being black and 1.0 white
	   1	    fades from blue (0.0) to yellow (1.0)
	   2	    fades from red (0.0) to blue (1.0), with
			    waves of green to form 'contours'
	   3	    pseudospectral
	   4	    inverted pseudospectral

Vertex type PCVVVX contains two scalar values. Most primitives will ignore the second value and apply the color map to the first value. The dp_rand_isosurf function will use the first set of values associated with each vertex to produce its isosurface, and color the surface by interpolation of the second set of values.

pshtdn

Purpose:

Close and shut down all renderers and DrawP3D.

Use:

pshtdn();

Parameters: none

Discussion:

This routine is intended to be called at the end of a program using DrawP3D. It closes and shuts down all initialized renderers, and does everything else necessary to terminate the session.

pshtrn

Purpose:

Close and shut down a renderer.

Use:

pshtrn( name );

Parameters:

Discussion:

This function closes and shuts down a renderer, destroying the renderer object. Once it has been shut down, the renderer cannot be reopened. Any reference to a GOB known to a renderer which has since been shut down is an error, and may result in a program crash. See also pshtdn, which shuts down all initialized renderers.

psnap

Purpose:

Cause a model to be rendered.

Use:

psnap( model, lights, camera );

Parameters:

model: character string giving the name of the GOB to be rendered

lights: character string giving the name of the lighting GOB to use

camera: character string giving the name of the camera to use

Discussion:

This function causes the renderer(s) to render the given GOB. The given lighting GOB provides the illumination model used, and the given camera provides the view.

psphr

Purpose:

Add a sphere primitive to the current GOB.

Use:

psphr();

Parameters: none

Discussion:

This function adds a sphere primitive to the current GOB. The sphere is 1.0 units in radius and is centered at the origin. It is expected that the user will use transformations to move it to the desired location and scale it to the desired size.

pstatt

Purpose:

Add an arbitrary string-valued attribute to the current GOB.

Use:

pstatt( name, string );

Parameters:

string: character string to be associated with name

Discussion:

This procedure can be used to add an arbitrary string attribute to a GOB.

pstcmp

Purpose:

Set the current color map function.

Use:

external mapfun

pstcmp( min, max, mapfun );

Parameters:

min: real value to be mapped to 0.0

max: real value to be mapped to 1.0

mapfun: user-supplied color mapping subroutine

Discussion:

When vertex lists of types containing scalar values (for example, PCVVX (4)) are rendered, the values are translated to colors by the current color map function. pstcmp allows the user to specify that function.

When translation occurs, the value is first rescaled into the interval from 0.0 to 1.0. If the value is beyond the range delimited by min and max, it maps to 0.0 if it is closer to min or 1.0 if it is closer to max. Otherwise, it maps to (value-min)/(max-min), which is in the range 0.0 to 1.0 inclusive. The mapped value is then passed to the subroutine mapfun, provided by the user, which is defined as follows:

	subroutine mapfun( val, r, g, b, a )
	real val, r, g, b, a

where val is the translated value. mapfun should then calculate red, green, blue, and opacity values, and store them in r, g, b, and a respectively. The subroutine can use any algorithm it wishes to do this, although fast algorithms are preferable as mapfun may be called many times. r, g, b, and a should be assigned values between 0.0 and 1.0 inclusive.

ptext

Purpose:

Add a text primitive to the current GOB.

Use:

ptext( text, loc, u, v );

Parameters:

text: character string giving text string of the primitive

loc: real array (3) giving the point where the text is to begin

u: real array (3) giving the writing direction vector

v: real array (3) giving the text up direction vector

Discussion:

This procedure adds a text primitive to the current GOB. The text is written starting at location, and running in the u direction such that vertical strokes run in the v direction. The height of text is controlled by the text-height attribute. The 'front' face of the text is determined by the cross product of u with v, so it is in the expected direction.

ptnsfm

Purpose:

Add an arbitrary transformation to a GOB.

Use:

ptnsfm( array );

Parameters:

array: real array(4,4) giving the transformation to be added

Discussion:

This function adds an arbitrary transformation to the current GOB. This transformation will be concatenated with the existing transformation by left multiplication; GOBs with no existing transformation effectively have the identity transformation associated with them. See the discussion of transformations in the User's Guide for information on the format of the transformation. Transformations are stored in array in column order, such that a translation by 3 units in the X direction could be created as follows:

	 real array(4,4)
	 data array/1.0, 0.0, 0.0, 0.0,
	$           0.0, 1.0, 0.0, 0.0,
	$           0.0, 0.0, 1.0, 0.0,
	$           3.0, 0.0, 0.0, 1.0/

ptorus

Purpose:

Add a torus primitive to the current GOB.

Use:

int ptorus( major, minor );

Parameters:

major: real major axis radius

minor: real minor axis radius

Discussion:

This function adds a torus primitive to the current GOB. The torus lies in the x-y plane, centered at the origin. The two parameters control the major and minor radii.

ptrans

Purpose:

Add a translation transformation to the current GOB.

Use:

ptrans( x, y, z );

Parameters:

xshift: real distance to translate in the X direction

yshift: real distance to translate in the Y direction

zshift: real distance to translate in the Z direction

Discussion:

This function adds a translation to the current GOB. This transformation will be concatenated with the existing transformation by left multiplication; GOBs with no existing transformation effectively have the identity transformation associated with them. See the discussion of transformations in the User's Guide for information on the format of the transformation.

ptratt

Purpose:

Add an arbitrary transformation-valued attribute to the current GOB.

Use:

ptratt( name, trnsfm );

Parameters:

transform: real array(4,4) giving the transformation to be associated with name

Discussion:

This procedure can be used to add an arbitrary transformation attribute to a GOB. Transformations are stored in array in column order, such that a translation by 3 units in the X direction could be created as follows:

	 real array(4,4)
	 data array/1.0, 0.0, 0.0, 0.0,
	$           0.0, 1.0, 0.0, 0.0,
	$           0.0, 0.0, 1.0, 0.0,
	$           3.0, 0.0, 0.0, 1.0/

ptrist

Purpose:

Add a triangle strip primitive to the current GOB.

Use:

ptrist( vtxtyp, ctype, npts, coords, colors, norms );

Parameters:

vtxtyp: integer vertex type specifier

ctype: integer color type (currently must be PRGB)

npts: integer number of vertices

coords: real array of coordinate data

colors: real array of color data

norms: real array of normal data

Discussion:

This function adds a triangle strip to the current GOB. There will be nvertices-2 triangles in the triangle strip. The first is defined by vertices 0, 1, and 2, the second (if present) by vertices 1, 2, and 3, and so on. For a description of the vertex data format, see the section on vertex lists in this document.

ptxtht

Purpose:

To set the text height attribute of the current GOB.

Use:

ptxtht( height );

Parameters:

height: real giving the character height of text primitives

Discussion:

This procedure sets the height for text primitives, by setting the value of the text-height attribute. Since the aspect ratio of the characters is preserved, the length of the text string is also effected.

pvcatt

Purpose:

Add an arbitrary vector-valued attribute to the current GOB.

Use:

pvcatt( name, x, y, z );

Parameters:

x: real x component of vector to be associated with name

y: real y component of vector to be associated with name

z: real z component of vector to be associated with name

Discussion:

This procedure can be used to add an arbitrary vector attribute to a GOB.

pzsurf

Purpose:

Create a Z surface composite GOB

Use:

pzsurf( vtype, zdata, vdata, nx, ny, crna, crnb, tfnull, tfun );

Parameters:

vtype: an integer vertex type specifier constant

zdata: an nx by ny array of reals specifying the z component

vdata: an nx by ny array of reals specifying values for coloring via the current color map

nx: integer: the number of vertices in the x direction

ny: integer: the number of vertices in the y direction

crna: real array (3) that specifies the starting corner

crnb: real array (3) that specifies the ending corner

tfnull: integer: if PTRUE, then include all points

tfun: a subroutine that excludes points from the Z surface.

Discussion:

This function draws a surface, rectangular in the x and y directions, the height of which is given by the data in the array zdata. Nx and ny specify the number of vertices in the x and y direction respectively.

If the vertex type requested is one which includes normal data, normals will be generated. This makes the surface look smoother, but increases the size of the model. If the vertex type includes value data, the user must supply a valdata array containing values for color mapping. Zdata and valdate are mapped from crna to crnb, so that the first point is at crna. From crna, the values are mapped in the x-direction, with increasing rows in the y direction. The z values of crna and crnb are ignored.

Tfun is a user supplied subroutine that determines whether a point should be excluded from the zsurface. It should be defined as follows:

	subroutine tfun( ixclde, value, i, j )
	integer ixclde, i, j
	real value

This function is called for each point in the surface, setting value to the z value at that point and i and j to the array indices (between 1 and nx and 1 and ny respectively) of the point in question. If on return from the function ixclde is PTRUE (1), the point will be excluded and a hole will be left in the surface at the appropriate point. If ixclde is PFALSE (0), the point will be included. This enables the user to remove points on the basis of position or value.