rtsi.com

home *** CD-ROM | disk | FTP | other *** search

/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / GRAPHICS / rayshade.lzh / DOC / rayshade.man < prev next >

Wrap

Text File | 1990-08-31 | 51KB | 1,189 lines

RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) NAME rayshade - a ray tracing program SYNOPSIS rayshade [ _o_p_t_i_o_n_s ] [ _f_i_l_e_n_a_m_e ] DESCRIPTION _R_a_y_s_h_a_d_e reads a file describing a scene to be rendered and produces a Utah Raster RLE format file of the ray-traced image. OPTIONS -C _r_e_d__c_o_n_t_r_a_s_t _g_r_e_e_n__c_o_n_t_r_a_s_t _b_l_u_e__c_o_n_t_r_a_s_t Set contrast factors used in controlling pixel subdivi- sion. -c Trace shadow rays through transparent objects. -E _e_y_e__s_e_p_a_r_a_t_i_o_n Set eye separation for stereo imaging. -F _r_e_p_o_r_t__f_r_e_q Set frequency, in lines, of status report (default 10). -h Print a short usage message. -j Perform jittered sampling. -L _s_t_a_r_t__l_i_n_e Begin trace on line _s_t_a_r_t__l_i_n_e, appending to image file (requires -O option). -l Render image for left eye (requires -E option). -n Do not trace shadow rays. -O _o_u_t_p_u_t__f_i_l_e Override image file name in input file, if any. -P _p_i_x_e_l__s_u_b_d_i_v_i_s_i_o_n_s Specifies the maximum number of times a pixel may be subdivided. -p Discard polygons with degenerate edges. -q Do not print warning messages. -R _x_r_e_s _y_r_e_s Set image resolution. -r Render image for right eye (requires -E option). Sun Release 4.0 Last change: September 11, 1989 1 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) -S _s_a_m_p_l_e_s Specifies number of jittered samples. -s Do not cache shadowing information. -T _t_h_r_e_s_h Specifies adaptive ray-depth cutoff threshold. -V _f_i_l_e_n_a_m_e Write verbose output to _f_i_l_e_n_a_m_e. -v Write verbose output to standard output. -W _w_o_r_k_e_r_s Specify number of worker processes (Linda version only). -w Write verbose worker information to the standard error (Linda version only). OVERVIEW _R_a_y_s_h_a_d_e is a ray tracing program capable of rendering images composed of a large number of primitive objects. _R_a_y_s_h_a_d_e reads a series of lines supplied on the standard input or contained in the file named on the command line. After reading the input file, _r_a_y_s_h_a_d_e renders the image. As each scanline is rendered, pixels are written to a Utah Raster RLE format image file. By default, this image file is written to the standard output, and information messages and statistics are written to the standard error. INPUT FILE FORMAT The input file consists of commands (denoted by keywords) followed by numerical or character arguments. Spaces, tabs, or newlines may be used to separate items in the file. Coordinates and vectors are specified in arbitrary floating-point units, and may be written with or without a decimal point. Colors are specified as red-green-blue floating-point triplets which indicate intensity and range from 0 (zero intensity) to 1. (full intensity). The following sections describe the keywords which may be included in the input file. Items in boldface type are literals, while square brackets surround optional items. VIEWING PARAMETERS eyep _x _y _z Specifies the eye's position in space. The default is (0, 20, 0). lookp _x _y _z Sun Release 4.0 Last change: September 11, 1989 2 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) Specifies the point at which the eye is looking. The default is (0, 0, 0). up _x _y _z Specifies the direction which should be considered "up" from the eye's position. Note that this vector need not be perpendicular to the vector between the look point and the eye's position. The default is (0, 0, 1.). fov _h_o_r_i_z_o_n_t_a_l__f_i_e_l_d__o_f__v_i_e_w [_v_e_r_t_i_c_a_l__f_i_e_l_d__o_f__v_i_e_w] The horizontal field of view specifies the angle, in degrees, between the left-most and right-most columns of pixels If present, the vertical field of view speci- fies the angle between the center of the top-most and bottom-most row of pixels. If not present, the verti- cal field of view is calculated using the screen reso- lution and the assumption that pixels are square. The default horizontal field-of-view is 45 degrees, while the default vertical field-of-view is calculated as described above. IMAGE GENERATION When specified in the input file, many of the image- generation commands may be overridden through command-line options. For example, the line "screen 1024 768" in an input file may be overridden by specifying "-R 128 128" on the command line. screen _x__r_e_s_o_l_u_t_i_o_n _y__r_e_s_o_l_u_t_i_o_n Specifies the horizontal and vertical resolution of the image to be rendered. This command may be overridden through use of the -R option. The default resolution is 512 by 512 pixels. background _r_e_d _g_r_e_e_n _b_l_u_e Specifies the color that should be assigned to rays which do not strike any object in the scene. The default is black (0, 0, 0). outfile _f_i_l_e_n_a_m_e Specifies the name of the file to which the resulting image should be written. By default, the image is written to the standard output. This command may be overridden through the use of the -O option. aperture _a_p_e_r_t_u_r_e__r_a_d_i_u_s The _a_p_e_r_t_u_r_e__r_a_d_i_u_s is the radius, in world units, of the aperture centered at the eye point. This controls, in conjunction with focaldist, the depth of field, and thus the amount of focus blur present in the final image. Rays are cast from various places on the Sun Release 4.0 Last change: September 11, 1989 3 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) aperture disk towards a point which is _f_o_c_a_l__d_i_s_t_a_n_c_e units from the center of the aperture disk. This causes objects which are _f_o_c_a_l__d_i_s_t_a_n_c_e units from the eye point to be in sharp focus. Note that an _a_p_e_r_t_u_r_e__r_a_d_i_u_s of zero causes a pinhole camera model to be used, and there will be no blurring (this is the default). Increasing the aperture radius leads to increased blurring. When using a non-zero aperture radius, it is best to use jittered sampling in order to reduce aliasing effects. focaldist _f_o_c_a_l__d_i_s_t_a_n_c_e Specifies the distance, in world units, from the eye point to the focal plane. Points which lie in this plane will always be in sharp focus. By keeping _a_p_e_r_t_u_r_e__r_a_d_i_u_s constant and changing _f_o_c_a_l__d_i_s_t_a_n_c_e, it is possible to create a sequence of frames which simulate pulling focus. By default, _f_o_c_a_l__d_i_s_t_a_n_c_e is equal to the distance from the eye point to the look point. maxdepth _m_a_x_i_m_u_m__d_e_p_t_h Controls the maximum depth of the ray tree. The default is 3, with eye rays considered to be of depth zero. cutoff _c_u_t_o_f_f__t_h_r_e_s_h_o_l_d Specifies the adaptive ray-depth cutoff threshold. When any ray's maximum contribution to the final color of a pixel falls below this value, the ray and its children (specularly transmitted and reflected rays) are not spawned. This threshold may be overridden through the use of the -T option. The default value is 0.001. jittered Use "jittered" sampling. This command may be overrid- den through the use of the -P option. The default is to use adaptive supersampling. adaptive _m_a_x__d_i_v_i_s_i_o_n_s Specifies that adaptive supersampling should be used, and that each pixel may be subdivided at most _m_a_x__d_i_v_i_s_i_o_n_s times. This command may be overridden through the use of the -j or -P options. The default value is one. samples _n_u_m__s_a_m_p_l_e_s Specifies the number of jittered samples. See SAMPLING for details. When specified, this value may be over- ridden through the use of the -S option. The default value is 3. Sun Release 4.0 Last change: September 11, 1989 4 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) contrast _r_e_d _g_r_e_e_n _b_l_u_e Specifies the maximum contrast allowed between samples in a (sub)pixel before subdivision takes place. See SAMPLING for details. When specified in the input file, these values may be overridden through the use of the -C option. The defaults for the red, green and blue channels are 0.25, 0.2, and 0.4, respectively. LIGHT SOURCES Three types of light sources are supported: point, extended (area), and directional. Point sources are specified by a location in world space and produce shadows with sharp edges. Extended sources are specified by a location and a radius. They produce shadows with "fuzzy" edges (penum- brae), but increase ray tracing time considerably. Direc- tional sources are specified by a direction. A maximum of 10 light sources may be defined. In the definitions below, _b_r_i_g_h_t_n_e_s_s specifies the intensity of the light source. If a single floating-point number is given, the light source emits a "white" light of the indi- cated normalized intensity. If three floating-point numbers are given, they are interpreted as the normalized red, green and blue components of the light source's color. Lights are defined as follows: light _b_r_i_g_h_t_n_e_s_s point _x _y _z Creates a point source located at ( _x, _y, _z ). light _b_r_i_g_h_t_n_e_s_s extended _x _y _z _r_a_d_i_u_s Creates an extended source centered at ( _x, _y, _z ) with the indicated _r_a_d_i_u_s. The images produced using extended sources are usually superior to those produced using point sources, but ray-tracing time is increased substantially. Rather than tracing one shadow ray to a light source, multiple rays are traced to various points on the extended source. The extended source is approximated by sampling a square grid of light sources. See SAMPLING for more details on the sampling of extended light sources. light _b_r_i_g_h_t_n_e_s_s directional _x _y _z Creates a directional light source whose direction vec- tor from each point in world space is defined as ( _x, _y, _z ). This vector need not be normalized. SURFACES Every primitive object has a surface associated with it. The surface specifies the color, reflectivity, and tran- sparency of an object. A surface may be defined anywhere in the input file, provided it is defined before it is used. Sun Release 4.0 Last change: September 11, 1989 5 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) Surfaces are defined once, and may be associated with any number of primitive objects. A surface definition is given by: _i_n_d_e_x [_t_r_a_n_s_l_u _s_t_c_o_e_f] surface _s_u_r_f__n_a_m_e _a_r _a_g _a_b _d_r _d_g _d_b _s_r _s_g _s_b _c_o_e_f _r_e_f_l _t_r_a_n_s_p _S_u_r_f__n_a_m_e is the name associated with the surface. This name must be unique for each surface. _A_r, _a_g and _a_b are used to specify the red, green, and blue components of the surface's ambient color. This color is always applied to a ray striking the surface. _D_r, _d_g and _d_b specify the diffuse color of the surface. This color, the _b_r_i_g_h_t_n_e_s_s component of each light source whose light strikes the surface, and dot product of the incident ray and the surface normal at the point of inter- section determine the color which is added to the color of the incident ray. _S_r, _s_g and _s_b are used to specify the specular color of the surface. The application of this color is controlled by the _c_o_e_f parameter, a floating-point number which indicates the power to which the dot product of the surface's normal vec- tor at the point of intersection and the vector to each light source should be raised. This number is then used to scale the specular color of the surface, which is then added to the color of the ray striking the surface. This model (Phong lighting) simulates specular reflections of light sources on the surface of the object. The larger _c_o_e_f is, the smaller highlights will be. _R_e_f_l is a floating-point number between 0 and 1 which indi- cates the reflectivity of the object. If non-zero, a ray striking the surface will spawn a reflection ray. The color assigned to that ray will be scaled by _r_e_f_l and added to the color of the incident ray. _T_r_a_n_s_p is a floating-point number between 0 and 1 which indicates the transparency of the object. If non-zero, a ray striking the surface will spawn a ray which is transmit- ted through the object. The resulting color of this transmitted ray is scaled by _t_r_a_n_s_p and added to the color of the incident ray. The direction of the transmitted ray is controlled by the _i_n_d_e_x parameter, which indicates the index of refraction of the surface. The optional parameters _t_r_a_n_s_l_u and _s_t_c_o_e_f may be used to give a surface a translucent appearance. _T_r_a_n_s_l_u is the translucency of the surface. If non-zero and a light source illuminates the side of the surface opposite that Sun Release 4.0 Last change: September 11, 1989 6 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) being rendered, diffuse lighting calculations are performed with respect to the side of the surface facing the light, and the result is scaled by _t_r_a_n_s_l_u and added to the color of the incident ray. Thus, _t_r_a_n_s_l_u accounts for diffuse transmission of light through the primitive. _S_t_c_o_e_f is similar to _c_o_e_f, but it applies to the specular transmission of highlights. Note that in both cases the index of refrac- tion of the surface is ignored. By default, surfaces have zero translucency. PRIMITIVES The ray tracer is capable of rendering a number of primitive objects. Primitives may be specified inside of an object- definition block, in which case they are added to the list of primitives belonging to that object. In addition, primi- tives may be defined outside of object-definition blocks. Primitives such as these are added to the list of primitives belonging to the World object. See below for more details. Rayshade usually ensures that a primitive's normal is point- ing towards the origin of the incident ray when performing shading calculations. Exceptions to this rule are tran- sparent primitives, for which rayshade uses the dot product of the normal and the incident ray to determine if the ray is entering or exiting the surface, and superquadrics, whose normals are never modified due to the nature of the ray/superquadric intersection code. Thus, all non- transparent primitives except superquadrics will in effect be double-sided. Primitives are specified by lines of the form: _p_r_i_m_i_t_i_v_e__t_y_p_e _s_u_r_f_a_c_e <_p_r_i_m_i_t_i_v_e _d_e_f_i_n_i_t_i_o_n> [_t_r_a_n_s_f_o_r_m_a_t_i_o_n_s] [_t_e_x_t_u_r_e _m_a_p_p_i_n_g _i_n_f_o_r_m_a_t_i_o_n] _S_u_r_f_a_c_e is the name of the surface to be associated with the primitive. Texture mapping and transforma- tions are discussed below. A list of available primi- tives follows. sphere _s_u_r_f_a_c_e _r_a_d_i_u_s _x_c_e_n_t_e_r _y_c_e_n_t_e_r _z_c_e_n_t_e_r Creates a sphere with the indicated _r_a_d_i_u_s centered at ( _x_c_e_n_t_e_r, _y_c_e_n_t_e_r, _z_c_e_n_t_e_r ). triangle _s_u_r_f_a_c_e _x_1 _y_1 _z_1 _x_2 _y_2 _z_2 _x_3 _y_3 _z_3 Creates a triangle with vertices ( _x_1, _y_1, _z_1 ), ( _x_2, _y_2, _z_2 ) and ( _x_3, _y_3, _z_3 ). Vertices should be given in a counter-clockwise order as one is looking at the 'top' face of the triangle. triangle _s_u_r_f_a_c_e _p_1_x _p_1_y _p_1_z _n_1_x _n_1_y _n_1_z _p_2_x _p_2_y _p_2_z _n_2_x _n_2_y _n_2_z _p_3_x _p_3_y _p_3_z _n_3_x _n_3_y _n_3_z Sun Release 4.0 Last change: September 11, 1989 7 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) Defines a Phong-shaded triangle. Here, the first three floating-point numbers specify the first vertex, the second three specify the normal at that vertex, and so on. Again, vertices should be specified in counter- clockwise order. Vertex normals need not be normalized. poly _s_u_r_f_a_c_e _x_1 _y_1 _z_1 _x_2 _y_2 _z_2 _x_3 _y_3 _z_3 [_x_4 _y_4 _z_4 ...] Creates a polygon with the specified vertices. The vertices should be given in a counter-clockwise order as one faces the "top" of the polygon. The polygon may be non-convex, but non-planar polygons will not be ren- dered correctly. The number of vertices defining a polygon is limited only by available memory. plane _s_u_r_f_a_c_e _x_n_o_r_m_a_l _y_n_o_r_m_a_l _z_n_o_r_m_a_l _x _y _z Creates a plane which passes through the point ( _x, _y, _z ) and has normal ( _x_n_o_r_m_a_l, _y_n_o_r_m_a_l, _z_n_o_r_m_a_l ). cylinder _s_u_r_f_a_c_e _x_b_a_s_e _y_b_a_s_e _z_b_a_s_e _x_t_o_p _y_t_o_p _z_t_o_p _r_a_d_i_u_s Creates a cylinder which extends from (_x_b_a_s_e, _y_b_a_s_e, _z_b_a_s_e) to (_x_t_o_p, _y_t_o_p, _z_t_o_p) and has the indicated _r_a_d_i_u_s. _t_o_p__r_a_d_i_u_s cone _s_u_r_f_a_c_e _x_b_a_s_e _y_a_s_e _z_b_a_s_e _x_t_o_p _y_t_o_p _z_t_o_p _b_a_s_e__r_a_d_i_u_s Creates a (truncated) cone which extends from (xbase, ybase, zbase) to (xtop, ytop, ztop). The bottom of the cone will have radius _b_a_s_e__r_a_d_i_u_s, while the top will have radius _t_o_p__r_a_d_i_u_s. heightfield _s_u_r_f_a_c_e _f_i_l_e_n_a_m_e Reads height field data from _f_i_l_e_n_a_m_e and creates a square height field of unit size centered at (0.5, 0.5). The height field is rendered as a surface tessellated by right isoscoles triangles. The binary data in the heightfield file is stored as an initial 32-bit integer giving the square root of number of data points in the file, termed the size of the height field. The size is followed by altitude (Z) values stored as 32-bit floating point values. The 0th value in the file specifies the Z coordinate of the lower- left corner of the height field (0, 0). The next specifies the Z coordinate for (1/(size-1), 0). The last specifies the coordinate for (1., 1.). In short, value number _i in the heightfield file specifies the Z coordinate for the point ( (i % size) / (size -1), (i / size) / (size -1) ). Non-square height fields may be rendered by specifying altitude values less than or equal to -1000. Triangles which have any vertex less than or equal in altitude to this value are not ren- dered. Be warned that the heightfield file is machine-dependent, as it is stored in binary format. Sun Release 4.0 Last change: September 11, 1989 8 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) box _s_u_r_f_a_c_e _x_c_e_n_t_e_r _y_c_e_n_t_e_r _z_c_e_n_t_e_r _x_s_i_z_e _y_s_i_z_e _z_s_i_z_e Creates a box centered at ( _x_c_e_n_t_e_r, _y_c_e_n_t_e_r, _z_c_e_n_t_e_r ) of size (2 * _x_s_i_z_e, 2 * _y_s_i_z_e, 2 * _z_s_i_z_e ). Although boxes must initially be aligned with the world axes, they may be transformed at will. superq _s_u_r_f_a_c_e _x_c_e_n_t_e_r _y_c_e_n_t_e_r _z_c_e_n_t_e_r _x_s_i_z_e _y_s_i_z_e _z_s_i_z_e _p_o_w_e_r Creates a superquadric with center ( _x_c_e_n_t_e_r, _y_c_e_n_t_e_r, _z_c_e_n_t_e_r, ) of total size (2 * _x_s_i_z_e, 2 * _y_s_i_z_e, 2 * _z_s_i_z_e, ). _P_o_w_e_r defines how closely the superquadric resembles the corresponding box. The larger the value of _p_o_w_e_r, the closer it will resemble the box (with rounded corners). A value greater than or equal to 1 is required for reasonable images. In addition, nei- ther transparent superquadrics nor superquadrics viewed from the interior will rendered correctly. OBJECTS One key feature of _r_a_y_s_h_a_d_e is its ability to treat groups of primitives as objects which may transformed and instan- tiated at will. Objects are composed of groups of primi- tives and/or other objects and are specified in the input file as: define _o_b_j_e_c_t__n_a_m_e [grid _x_v_o_x_e_l_s _y_v_o_x_e_l_s _z_v_o_x_e_l_s] [list] [primitives] [instances] defend [texturing information] The ordering of the various elements inside the object- definition block is inconsequential. Here, [_i_n_s_t_a_n_c_e_s] are any number of declarations of the form: object _o_b_j_e_c_t__n_a_m_e [_t_r_a_n_s_f_o_r_m_a_t_i_o_n_s] [_t_e_x_t_u_r_i_n_g _i_n_f_o_r_m_a_t_i_o_n] This causes a copy of the named object to be made, transformed and textured as requested, and added to the object being defined. An object must be defined before it may be instantiated, which ensures that no cycles appear in the object-definition graph. A special object named _W_o_r_l_d is maintained internally by _r_a_y_s_h_a_d_e. Primitive definitions and object instantiations which do not appear inside an object-definition block are added to this object. When performing ray tracing, rays are intersected with the objects that make up the World object. Internally, objects are stored by one of two means. By default, groups of primitives which make up an object are stored in a _l_i_s_t. The constituents of such an object are stored in a simple linked-list. When a ray is intersected Sun Release 4.0 Last change: September 11, 1989 9 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) with such an object, the ray is tested for intersection with each object in the list. While the list is the default method of object storage, one may emphasize this fact in the input file by including the list keyword somewhere within the object-definition block. The second form of internal object storage is the three- dimensional _g_r_i_d. The grid's total size is calculated by _r_a_y_s_h_a_d_e and is equal to the bounding box of the object that is engridded. A grid subdivides the space in which an object lies into an array of uniform box-shaped _v_o_x_e_l_s. Each voxel contains a linked-list of objects and primitives which lie within that voxel. When intersecting a ray with an object which is stored in a grid, the ray is traced incre- mentally from voxel-to-voxel, and the ray is tested for intersected against each object in the linked list of each voxel that is visited. In this way the intersection of a ray with a collection of objects is generally made faster at the expense of increased storage requirements. This form of object representation is enabled by including the the grid keyword somewhere within the object-definition block: grid _x_v_o_x_e_l_s _y_v_o_x_e_l_s _z_v_o_x_e_l_s Stores the object being defined as a grid consisting of a total of (xvoxels * yvoxels * zvoxels) voxels, with _x_v_o_x_e_l_s along the x-axis of the grid, _y_v_o_x_e_l_s along the y-axis, and _z_v_o_x_e_l_s along the z-axis. For reasonably complex objects, a value of 20 for each parameter usu- ally works well. For convenience, one may also define surfaces inside of an object-definition block. Surfaces defined in this manner are nevertheless globally available. In addition, object definitions may be nested. This facili- tates the definition of objects through the use of recursive programs. TRANSFORMATIONS _R_a_y_s_h_a_d_e allows for the application of arbitrary linear transformations to primitives and compound objects. The specification of transformations occurs immediately follow- ing the specification of a primitive or instantiation of an object. Any number of transformations may be composed; the resulting total transformation is applied to the entity being transformed. Transformations are specified by: translate _x _y _z Translate the object by ( _x, _y, _z). Sun Release 4.0 Last change: September 11, 1989 10 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) rotate _x _y _z _t_h_e_t_a Rotate the object counter-clockwise about the vector ( _x, _y, _z ) by _t_h_e_t_a degrees. scale _x _y _z Scale the object by ( _x, _y _z ). transform _x_1 _y_1 _z_1 _x_2 _y_2 _z_2 _x_3 _y_3 _z_3 Transform the object by the column-major matrix speci- fied by the nine floating-point numbers. Thus, a point (x, y, z) on the surface of the object is mapped to (x*x1 + y*y1 + z*z1, x*x2 + y*y2 + z*z2, x*x3 + y*y3 + z*z3). TEXTURE MAPPING _R_a_y_s_h_a_d_e provides a means of applying solid procedural tex- tures to surfaces of primitives. This is accomplished by supplying texture mapping information immediately following the definition of a primitive, object, or instance of an object. This allows one to texture individual primitives, objects, and individual instances of objects at will. Tex- turing information is supplied via a number of lines of the following form: texture _t_e_x_t_u_r_e__t_y_p_e [_a_r_g_u_m_e_n_t_s] [_t_r_a_n_s_f_o_r_m_a_t_i_o_n_s] _T_e_x_t_u_r_e__t_y_p_e is the name of the texture to apply. _A_r_g_u_m_e_n_t_s are any arguments that the specific texture type requires. If supplied, the indicated _t_r_a_n_s_f_o_r_m_a_- _t_i_o_n_s will be applied to the texture. (More accu- rately, the inverse of the supplied transformation is applied to the point of intersection before it is passed to the texturing routines.) Versions of Perlin's Noise() and DNoise() functions are used to generate values for most of the interesting textures. There are eight available textures: bump _s_c_a_l_e Applies a random bump map to the surface being tex- tured. The point of intersection is passed to DNoise(). The returned normalized vector is weighted by _s_c_a_l_e and added to the normal vector at the point of intersection. checker _s_u_r_f_a_c_e Applies a (3D) checkerboard texture to the object being textured. Every point that falls within an "even" cube will be shaded using the characteristics of the named surface. Every point that falls within an "odd" cube will retain its usual surface characteristics. Be warned that strange effects due to roundoff error are possible when the planar surface of an object lies in a Sun Release 4.0 Last change: September 11, 1989 11 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) plane of constant integral value in texture space. blotch _b_l_e_n_d__f_a_c_t_o_r _s_u_r_f_a_c_e This texture produces a mildly interesting blotchy- looking surface. _B_l_e_n_d__f_a_c_t_o_r is used to control the interpolation between a point's default surface charac- teristics and the characteristics of the named surface. A value of 0 results in a roughly 50-50 mix of the two surfaces. Higher values result in greater instances of the 'default' surface type. fbm _o_f_f_s_e_t _s_c_a_l_e _H _l_a_m_b_d_a _o_c_t_a_v_e_s _t_h_r_e_s_h [_c_o_l_o_r_m_a_p] This texture generates a sample of discretized frac- tional Brownian motion (fBm) and uses it to modify the diffuse and ambient components of an object's color. If no _c_o_l_o_r_m_a_p is named, the sample is used to scale the object's diffuse color. If a _c_o_l_o_r_m_a_p name is given, a 256-entry colormap is read from the named file, and the object is colored using the values in this colormap (see below). _S_c_a_l_e is used to scale the output of the fractional Brownian motion function. _O_f_f_s_e_t allows one to control the minimum value of the fBm function. _H is related to the _H_o_l_d_e_r _c_o_n_s_t_a_n_t used in the fBm (a value of 0.5 works well). _L_a_m_b_d_a is used to control the _l_a_c_u_n_a_r_i_t_y, or spacing between succes- sive frequencies, in the fBm (a value of 2.0 will suf- fice). _O_c_t_a_v_e_s specifies the number of octaves of Noise() to use in simulating the fBm (5 to 7 works well), and _t_h_r_e_s_h is used to specify a lower bound on the output of fBm function. Any value lower than _t_h_r_e_s_h is set to zero. fbmbump _o_f_f_s_e_t _s_c_a_l_e _H _l_a_m_b_d_a _o_c_t_a_v_e_s This texture is similar to the fbm texture. Rather modifying the color of a surface, fbmbump acts as a bump map. gloss _g_l_o_s_s_i_n_e_s_s This texture gives reflective surfaces a glossy appear- ance. A glossy object's surface normal is perturbed such that it 'samples' a cone of unit height with radius 1. - _g_l_o_s_s_i_n_e_s_s. Thus, a value of 1 results in perfect mirror-like reflections, while a value of 0 results in extremely fuzzy reflections. For best results, jittered sampling should be used when render- ing scenes containing glossy objects. marble [_c_o_l_o_r_m_a_p] This texture gives a surface a marble-like appearance. The texture is implemented as roughly parallel alter- nating veins of marble, each of which is separated by 1/7 of a unit and runs perpendicular to the Z axis. If Sun Release 4.0 Last change: September 11, 1989 12 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) the name of a _c_o_l_o_r_m_a_p file is given, the marble will be colored using the RGB values in the colormap. If no colormap name is given, the diffuse and ambient com- ponents of the object's surface are simply scaled. One may transform the texture to control the density of the marble veins. wood This texture gives a wood-like appearance to a surface. The feature size of the texture is approximately 1/100th of a unit, making it often necessary to scale the texture in order to achieve the desired appearance. A colormap is an ASCII file 256 lines in length, each line containing three space-separated integers ranging from 0 to 255. The first number on the nth line specifies the red component of the nth entry in the colormap, the second number the green component, and the third the blue. The values in the colormap are normalized before being used in texturing functions. Textures which make use of colormaps generally compute an index into the colormap and use the corresponding entry to scale the ambient and diffuse com- ponents of a surface's color. It is important to note that more than one texture may be applied to an object at any time. In addition to being able to apply more than one texture directly (by supplying multi- ple "texturing information" lines for a single object), one may instantiate textured objects which, in turn, may be tex- tured or contain instances of objects which are textured, and so on. ATMOSPHERIC EFFECTS _R_a_y_s_h_a_d_e has the capability of including several kinds of atmospheric effects when rendering an image. Currently, two such effects are available: fog _t_h_i_n_n_e_s_s _r_e_d _g_r_e_e_n _b_l_u_e Add global exponential fog with the specified _t_h_i_n_n_e_s_s and color. Fog is simulated by blending the color of the fog with the color of each ray. The amount of fog color blended into a ray color is an exponential func- tion of the distance from the ray origin to the point of intersection divided by _t_h_i_n_n_e_s_s. If the distance divided by _t_h_i_n_n_e_s_s is equal to 1, a ray's new color will be half of the fog color plus half its original color. mist _r_e_d _g_r_e_e_n _b_l_u_e _t_r_a_n_s._r_e_d _t_r_a_n_s._g_r_e_e_n _t_r_a_n_s._b_l_u_e _z_e_r_o _s_c_a_l_e Add global low-altitude mist of the specified color. The color of a ray is modulated by a fog with density which varies linearly with the difference in altitude Sun Release 4.0 Last change: September 11, 1989 13 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) (Z coordinate) between the ray origin and the point of intersection. The three trans values specify the transmissivity (thinness) of the mist for each of the red, green and blue channels. The base altitude of the mist is given by _z_e_r_o, and the apparent height of the mist can be controlled by _s_c_a_l_e, which is used to scale the difference in altitude. SAMPLING This section clarifies how antialiasing and sampling of extended light sources are accomplished. Two types of anti-aliasing are supported; adaptive subdivision and so- called "jittered sampling". Adaptive subdivision works by sampling each pixel at its corners. The contrast between these four samples is com- puted, and if too large, the pixel is subdivided into four equivalent sub-pixels and the process is repeated. The threshold contrast may be controlled via the -C option or the contrast command. There are separate thresholds for the red, green, and blue channels. If the contrast in any of the three is greater than the appropriate threshold value, the pixel is subdivided. The pixel-subdivision process is repeated until either the samples' contrast is less than the threshold or the maximum pixel subdivision level, specified via the -P option or the adaptive command, is reached. When the subdivision process is complete, a weighted average of the samples is taken as the color of the pixel. Jittered sampling works by dividing each pixel into a number of square regions and tracing a ray through _s_o_m_e point in each region. The exact location in each region is chosen randomly. The number of regions into which a pixel is sub- divided is specified through the use of the -S option. The integer following this option specifies the square root of the number of regions. Each extended light source is, in effect, approximated by a square grid of light sources. The length of each side of the square is equal to the diameter of the extended source. Each array element, which is square in shape, is in turned sampled by randomly choosing a point within that element to which a ray is traced from the point of intersection. If the ray does not intersect any primitive object before it strikes a light source element, there is said to be no sha- dow cast by that portion of the light source. The fraction of the light emitted by an extended light source which reaches the point of intersection is the number of elements which are not blocked by intervening objects divided by the total number of elements. The fraction is used to scale the intensity (color) of the light source, and this scaled intensity is then used in the various lighting calculations. Sun Release 4.0 Last change: September 11, 1989 14 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) When jittered sampling is used, one shadow ray is traced to each extended source per shading calculation. The element to be sampled is determined by the region of the pixel through which the eye ray at the top of the ray tree passed. When adaptive supersampling is used, the -S option or the samples command controls how may shadow rays are traced to each extended extended light source per shading calculation. Specifically, each extended source is approximated by a square array consisting of _s_a_m_p_l_e_s * _s_a_m_p_l_e_s elements. How- ever, the corners of the array are skipped to save rendering time and to more closely approximate the circular projection of an extended light source. Because the corners are skipped, _s_a_m_p_l_e_s must be at least 3 if adaptive supersam- pling is being used. Note that the meaning of the -S option (and the samples com- mand) is different depending upon whether or not jittered sampling is being used. While jittered sampling is generally slower than adaptive subdivision, it can be beneficial if the penumbrae cast by extended light sources take up a relatively large percentage of the entire image or if the image is especially prone to aliasing. EXAMPLES A very simple _r_a_y_s_h_a_d_e input file might be: light 1.0 directional 1. 1. 1. surface red .2 0 0 .8 0 0 .5 .5 .5 32. 0.8 0. 1. surface green 0 .2 0 0 .8 0 0 0 0 0. 0. 0. 1. sphere red 8. 0. 0. -2. plane green 0. 0. 1. 0. 0. -10. Passing this input to _r_a_y_s_h_a_d_e will result in an image of a red reflective sphere sitting on a white ground-plane being written to the standard output. Note that in this case, default values for eyep, lookp, up, screen, fov, and back- ground are assumed. A more interesting example uses instantiation to place mul- tiple copies of an object at various locations in world space: eyep 10. 10. 10. fov 20 light 1.0 directional 0. 1. 1. surface red .2 0 0 .8 0 0 .5 .5 .5 32. 0.8 0. 1. Sun Release 4.0 Last change: September 11, 1989 15 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) surface green 0 .2 0 0 .8 0 0 0 0 0. 0. 0. 1. surface white 0.1 0.1 0.1 0.8 0.8 0.8 0.6 0.6 0.6 30 0 0 0 define blob sphere red 0.5 .5 .5 0. sphere white 0.5 .5 -.5 0. texture marble scale 0.5 0.5 0.5 sphere red 0.5 -.5 -.5 0. sphere green 0.5 -.5 .5 0. defend object blob translate 1. 1. 0. object blob translate 1. -1. 0. object blob translate -1. -1. 0. object blob translate -1. 1. 0. grid 20 20 20 Here, an object named _b_l_o_b is defined to consist of four spheres, two of which are red and reflective. The object is stored as a simple list of the four spheres. The _W_o_r_l_d object consists of four instances of this object, translated to place them in a regular pattern about the origin. Note that since the marbled sphere was textured in "sphere space" each instance of that particular sphere has exactly the same marble texture applied to it. Of course, just as the object _b_l_o_b was instantiated as part of the _W_o_r_l_d object, one may instantiate objects as part of any other object. For example, a series of objects such as: define wheel sphere tire_color 1. 0 0 0 scale 1. 0.2 1. sphere hub_color 0.2 0 0. 0 defend define axle object wheel translate 0. 2. 0. object wheel translate 0. -2. 0. cylinder axle_color 0. -2. 0. 0. 2. 0. 0.1 defend define truck box truck_color 0. 0. 0. 5. 2. 2. /* Trailer */ box truck_color 6. 0 -1 2 2 1 /* Cab */ object axle translate -4 0 -2 object axle translate 4. 0. -2. defend could be used to define a very primitive truck-like object. RENDERING HINTS Ray tracing is a computationally intensive process, and rendering complex scenes can take hours of CPU time, even on Sun Release 4.0 Last change: September 11, 1989 16 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) relatively powerful machines. There are, however, a number of ways of attempting to reduce the running time of the pro- gram. The first and most obvious way is to reduce the number of rays which are traced. This is most simply accomplished by reducing the resolution of the image to be rendered. The -P option may be used to reduce the maximum pixel subdivision level. A maximum level of 0 will speed ray tracing consid- erably, but will result in obvious aliasing in the image. By default, a pixel will be subdivided a maximum of one time, giving a maximum of nine rays per pixel total. Alternatively, the -C option or the contrast command may be used to decrease the number of instances in which pixels are subdivided. Using these options, one may indicate the max- imum normalized contrast which is allowed before supersam- pling will occur. If the red, green or blue contrast between neighboring samples (taken at pixel corners) is greater than the maximum allowed, the pixel will be subdi- vided into four sub-pixels and the sampling process will recurse until the sub-pixel contrast is acceptable or the maximum subdivision level is reached. The number of rays traced can also be lowered by making all surfaces non-reflecting and non-refracting or by setting maxdepth to a small number. If set to 0, no reflection or refraction rays will be traced. Lastly, using the -n option will cause no shadow rays to be traced. In addition, judicious use of the grid command can reduce rendering times substantially. However, if an object con- sists of a relatively small number of simple objects, it will likely take less time to simply check for intersection with each element of the object than to trace a ray through a grid. The C pre-processor can be used to make the creation and managing of input files much easier. For example, one can create "libraries" of useful colors, objects, and viewing parameters by using #define and #include. To use such input files, run the C pre-processor on the file, and pipe the resulting text to rayshade. FILES Examples/* example input files AUTHORS _R_a_y_s_h_a_d_e had its beginnings as an "introductory" public- domain ray tracer written by Roman Kuchkuda. Vestiges of his code may be found in rayshade, particularly in the names of variables and the superquadric code. The first version Sun Release 4.0 Last change: September 11, 1989 17 RAYSHADE(1G) USER COMMANDS RAYSHADE(1G) of _r_a_y_s_h_a_d_e was written at Princeton University during 1987-88 by Craig Kolb, David C. Hoffman, and David P. Dob- kin. The current manifestation of _r_a_y_s_h_a_d_e was written dur- ing the fall of 1988 by Craig Kolb. The Noise() and DNoise() routines which form the basis of many of the tex- turing functions were written by Robert Skinner and Ken Mus- grave. The depth of field code appears courtesy of Rodney G. Bogart. CAVEATS _R_a_y_s_h_a_d_e performs no automatic hierarchy construction. The intelligent placement of objects in grids and/or lists is entirely the job of the modeler. While transparent objects may be wholly contained in other transparent objects, rendering partially intersecting tran- sparent objects with different indices of refraction is, for the most part, nonsensical. _R_a_y_s_h_a_d_e is capable of using large amounts of memory. In the environment in which it was developed (machines with at least 8 Megabytes of physical memory plus virtual memory), this has not been a problem, and scenes containing several billion primitives have been rendered. On smaller machines, however, memory size can be a limiting factor. The "Total memory allocated" statistic is the total space allocated by calls to malloc. It is _n_o_t the memory high- water mark. After the input file is processed, memory is only allocated when refraction occurs (to push media onto a stack) and when ray tracing height fields (to dynamically allocate triangles). The image produced will always be 24 bits deep. Explicit or implicit specification of vectors of length less than _e_p_s_i_l_o_n (1.E-6) results in undefined behavior. SEE ALSO rle(5) Sun Release 4.0 Last change: September 11, 1989 18