Amiga Tools 4

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

/ Amiga Tools 4 / Amiga Tools 4.iso / grafix / raytracing / raylab / docs / raylab.doc < prev

Wrap

Text File | 1996-02-17 | 39.7 KB | 1,137 lines

R A Y L A B version 1.0 rev 1 Users Documentation (c)1995-1996 by Marcus Geelnard Table of contents ----------------- 1 INTRODUCTION 1.1 Intentions with RayLab 1.2 What does RayLab do? 2 FEATURES 2.1 Primitives 2.2 Textures 2.3 Transforms 2.4 Antialiasing 2.5 Display 3 HOW TO CREATE 3D IMAGES WITH RAYLAB 3.1 An example scene 4 LANGUAGE REFERENCE 4.1 Primitives 4.1.1 Sphere 4.1.2 Ellipsoid 4.1.3 Plane 4.1.4 Box 4.1.5 Triangle 4.1.6 Disc 4.1.7 Cylinder 4.2 Lights 4.3 Camera 4.3.1 Location 4.3.2 Viewpoint 4.3.3 Aspect 4.4 Textures 4.4.1 Color 4.4.2 Colormap 4.4.3 Pattern 4.4.3.1 checker 4.4.3.2 circles 4.4.3.3 rings 4.4.3.4 spots 4.4.3.5 gradient 4.4.3.6 none 4.4.4 Reflect 4.4.5 Diffuse 4.4.6 Ambient 4.4.7 Phong 4.4.8 Phongsize 4.4.9 Default 4.5 Deftexture 4.6 Transform 4.6.1 Scale 4.6.2 Move 4.6.3 Rotate 4.6.4 None 4.7 Deftransform 4.8 Globals 4.8.1 Picwidth 4.8.2 Picheight 4.8.3 Backgroundcolor 4.8.4 Recdepth 4.8.5 Display 4.8.6 Antialiasrec 4.8.7 Antialiasthreshold 4.9 Comments 5 MISCELLANEOUS 5.1 How to contact the author 5.2 Legal stuff 5.3 Past, present and the future 5.4 Comments by the author 1. INTRODUCTION ================ 1.1 Intentions with RayLab -------------------------- My intention with RayLab was, first of all, to create a decent raytracer based on my newfound (rather limited) knowledge in linear algebra, as I took a course in that particular subject at the university. I also wanted to improve my skills in C-programming (this is my third 'real' C program). As it turned out it was not hard at all to create a working program, and after about a week of programming I could already produce good looking pictures with shades, reflect- ions, highlights, texture-patterns and several different shape primitives. A working (but primitive) description language had also been introduced success- fully at that time. RayLab is rather slow as it is not really optimized in any way, and that is the way I intend to keep it. I am more interested in getting a working program with (more or less) powerful features than a sporting competitor to those other brilliant raytracers, developed by far more experienced persons than me. It may also be mentioned that I have not bothered to look up any information on ray- tracing in particular, as I am more interested in putting geometry theory into practice than to produce a commercial program. But feel free to enjoy it anyway! 1.2 What does RayLab do? ------------------------ RayLab is capable of producing realistic three-dimensional images using a tech- nique called 'raytracing'. What it basically means is that you place 3D objects in a space (room, world, scene or whatever you like to call it). Then you add some light-sources and a camera. What the raytracer does is to mathematically calculate what the picture would look like, if it was to be taken by a real camera. This is done by dividing the picture into small elements (pixels) and for each element, a ray (or beam) is casted, from the camera out into the three-dimensional space. If this ray 'hits' an abject, some steps are taken: 1) The color of the object is checked. 2) The light from different light-sources are checked, and also another ray (from the point on the object to the light-source(s)) is casted to see if any other objects block the light. This way shadows are produced. 3) If the object is reflective, a new ray will be casted to see if any other objects are visible thorugh reflection of the first object. 4) If the object is transparent, a new ray will be produced which continues on the other side of the surface of the object (this is not supported in RayLab yet, unfortunately). The information from all these calculations is used to set the color of the pixel in the picture. This procedure is repeated for every ray, including all 'camera-rays' and those produced by reflection and transparency. As you would probably guess, this requires a great deal of computation. On a normal personal computer calcualtion times of several hours are not too uncommon (a processor with good floating point performance is strongly recommended). 2 FEATURES =========== RayLab is a program that will probably be updated with new features every now and then, as I like experimenting with new effects, but for now we will have to settle for a rather limited set of features. 2.1 Primitives --------------- Primitives are the basic shapes that make the building blocks of objects. Some raytracers are specialized at only handling objects built up from triangles (just as a 2D object can be built up from lines, a 3D object can be described by triangles, but only roughly), but RayLab handles several different shapes. Those are (at the moment): sphere (perfectly round), ellipsoid, plane (infinitly long and wide), box, triangle, disc and cylinder. 2.2 Textures ------------- As we all know, an object needs to have a surface texture. In RayLab this means a set of properties that describes the looks and feels of a surface. The different properties are: color (or set of color-shades), pattern, diffuse reflection (color intensity proportional to surrounding light-sources), high- light intensity and concentration, ambient light, and finally reflection. Important properties that have been 'left out' are transparency and refraction. This will certainly be implemented in the next major release of RayLab. 2.3 Transforms --------------- In the common case, primitives and textures do not always match the object shape and look that you want. Therefor you may need to transform a shape and/or texture into what you need for your specific needs. For instance the box primitive is always aligned along the x-y-z-axises, which is not always conv- enient when you want to construct complex scenes. This is where the transform- ation facilities of RayLab come in handy; just apply a rotation to the box to make it fit into your scene. All primitives can be transformed in one of the following ways: scaling, movement (displacement) and rotation. This is also valid for all textures. Be warned though: transformation can consume very much computation power, especially rotation of primitives, so do not use it unless you need it (or have a monster computer). 2.4 Antialiasing ----------------- When you render a picture with a computer program such as RayLab, chanses are that the picture will look too 'jaggy'. This is because the pixels on the computer screen are square, and often visible to the eye. With antialiasing this rough look can be eliminated. The idea is to use several rays per pixel, and calculate the average color found by these rays. This method gives a very smooth and realistic appearance, but it also consumes more computation power. 2.5 Display ------------ One useful feature of RayLab is that it can display the output picture to your screen while rendering it. This is good for displaying previews. Currently only the Amiga version of RayLab has support for graphical displays, but I hope for more persons to develop display routines for different platforms. 3 HOW TO CREATE 3D IMAGES WITH RAYLAB ====================================== To have RayLab create a picture for you, you first have to describe the pict- ure to it. This is done by setting up a 'scene', which can be created in any text-editor or word-processor that can save raw ascii files (Amiga: ced, ed, PC: edit, Unix: vi, emacs, nedit... etc.). The description is made in a special language, which will be described in detail in chapter 4. In the scene you will need to have at least one object and one light-source. You will probably want to set up a camera and a few parameters aswell (such as picture width and height). 3.1 An example scene --------------------- To get to know a program or programming language, it is always wise to look at demonstration examples. So to get things started, here is an example of a complete scene description (detailed explanations will follow). This scene can also be found in the scenes directory, named 'demo1.rl': ------------8X-------------------------------------------------------------- Globals: picwidth 320 # Image dimensions: 320x240 picheight 240 backgroundcolor 0 0 0 # Red=0, green=0, blue=0 => black :end Sphere: centre 0 0 2 # Place the sphere in x=0, y=0, z=2 radius 2 # ...and it will have a radius of 2 units :end Light: location 3 -8 4 # A light-source at x=3, y=-8, z=4 color 1 1 1 # Red=1.0, green=1.0, blue=1.0 => white :end Camera: location -1 -9 2 # Place the camera in x=-1, y=-9, z=2 viewpoint 0 0 2 # Look at x=0, y=0, z=2 :end ------------8X-------------------------------------------------------------- On the first line, the keyword 'Globals:' is found. This means that the next section will contain some information that is global to the whole scene. This section is ended by the keyword ':end' on line five. On the second line the picture width is declared by 'picwidth 320'. Next follows a comment, which is started by a '#' and ended by the end of the line. On the next line the picture height is declared. The fourth line says 'backgroundcolor 0 0 0', which means that the background color should be black. All colors in RayLab are described by their red, green and blue components, in that order, each component ranging from 0.0 (min) to 1.0 (max). The next section describes a primitive. This primitive is a sphere with its centre in (0,0,2), and the radius 2. All points and vectors in RayLab are de- scribed by their x, y and z components, and are aligned to a right-hand system. This means that the x-axis pionts right, the y-axis away and the z-axis points upwards. The sphere is not given a texture, so it will use the default texture. The default texture is, if none else given, a non-reflective dull red surface. The third section describes a light-source, which is located at (3,-8,4) and has the color white (all three components are set to their maximum value 1.0). The light-source casts its light all the way to the infinity in all directions. Last, but not least, a camera is set up. The parameters location and viewpoint sort of speaks for themselves. To finally render (compute) the picture which is described by this scene, you just have to call RayLab from your shell (cli, dos, or whatever) with the following syntax: raylab description-file picture-file ...where description-file is the file that contains the descrition text (i.e. the example above), and the picture-file is the output image file, which will be saved in targa 24-bit format (.tga). To render the example above, type: raylab scenes/demo1.rl demo1.tga That will produce a targa picture named 'demo1.tga'. 4 LANGUAGE REFERENCE ===================== The description language that RayLab uses is very simple, although you may argue that it can look a bit dull (I agree). I have tried to make the interpr- eter as flexible as possible though to leave the layout to the user. This has been accomplished by the following means: o Keywords can be entered in any order. o RayLab is totally case insensitive (SpHeRe: is the same thing as SPHERE:) o RayLab does not differ between spaces, tabs and line-feeds (except when you use comments), so indents, line-spaces etc. does not make a difference to RayLab; e.g. you can write several keywords on one line. o In many cases you can leave some keywords out. This will result in that RayLab will use default settings for those keywords that are not specified. A description is built up from several "sections", each section biginning with a keyword with a terminating colon (e.g. Box:), and ending with :end. Sections may also have sub-sections. For instance a primitive may have a texture speci- fication, which is also a section. 4.1 Primitives --------------- As mentioned before, the so called primitvies are the actual shapes that you will use to build your scene. Each primitive is declared by creating a section that describes the primitive. 4.1.1 Sphere The sphere primitive is a classic round shape, which is defined by its location in space (centre) and its radius. Example: Sphere: centre 0 0 3 radius 2 :end The default sphere has the radius 1.0 and has its centre at (0,0,0). 4.1.2 Ellipsoid The ellipsoid is a more or less redundant shape, as it can be produced from a scaled sphere, but it was the first primitive introduced in RayLab and as such is kept due to nostalgic reasons. Unlike the sphere, the ellipsoid needs three values to describe the radius, one for each axis. Example: Ellipsoid: centre 0 0 3 radius 2 1.5 4 :end The default ellipsoid has the radius (1,1,1) and is located at (0,0,0). 4.1.3 Plane A plane is an infinitely long and wide, totally flat surface. It is defined by its surface normal, which is orthogonal to the surface, and its offset along this normal. This example shows a plane which could be described as all points (x,y,z) which has x=-1 (regardless of y and z): Plane: normal 1 0 0 offset -1 :end The default plane has the surface normal (0,0,1) and offset 0.0, i.e. it stretches along the x and y axis. 4.1.4 Box The box is simply a polyhedron with six sides, like a dice. It is described by two points in space. For instance, a cube with its eight courners: (0,0,0), (2,0,0), (2,2,0), (0,2,0), (0,0,2), (2,0,2), (2,2,2), (0,2,2), would look like this described to RayLab: Box: corners 0 0 0 2 2 2 :end Thus each side of the box is always parallel to two of the axises. To create a box with any alignment, you can simply transform it. The default box is a box with the corners (0,0,0), (1,1,1). 4.1.5 Triangle A triangle is defined by its three corners in space. Example: Triangle: corners 0 0 -1 3 -2 4 -5 -1 3 :end The default triangle has the corners (0,0,0), (1,1,1), (-1,1,1). 4.1.6 Disc The disc is an infinitely thin surface, just like the plane. The difference between the plane and the disc, is that the disc has a radius, whereas the plane is infinitely long and wide. Thus the disc looks like a disc (he-he). The defin- ition of a disc requires three parameters: centre, normal and radius. Example: Disc: centre 2 -3 2 normal 1 -2 1 radius 1.5 :end The default disc has the following settings: centre: (0,0,0) normal: (0,0,1) radius: 1 4.1.7 Cylinder The cylinder is defined by its radius and its height, and it always has the z- axis as its centre axis. The ends of the cylinder are "closed" by two discs (all in the spirit of solid geometry). The centre of the first end is always (0,0,0), while the second end is located at (0,0,height). Just transform the cylinder to make it fit your needs. This example demonstrates a cylinder that lies along the x-axis, with its ends in (-3,0,0) and (3,0,0): Cylinder: radius 1.4 height 6 transform: rotate 0 90 0 move -3 0 0 :end :end The default cylinder has a radius of 1.0 and the height 1.0. 4.2 Lights ----------- Every scene needs at least one light-source. Light-sources in RayLab are s.c. point lights, which means that they cast their light in all directions, and they are infinitely small (you can not see them if you turn your camera to look at them). Light-sources can have different colors, and thereby also different intensities (a grey light-source does not give as much light as a white light-source does). A light-source is simply defined by a location and a color. Example: Light: location -20 -30 40 color 1.0 0.0 0.0 :end This will place a red light-source at (-20,-30,40). The default light-source is located at (10,-10,10), and has the color white. 4.3 Camera ----------- The camera is indeed a very important part of the scene. The camera does not have a shape, and will not be seen through a mirror or alike, but it can be manipulated to change the appearance of a picture drastically. 4.3.1 Location The camera can be placed anywhere in space. This is given by the keyword location. The default location is (0,-10,1). 4.3.2 Viewpoint When the camera has been placed, it also needs to be directed to look at some point in space. In RayLab you only have to tell where to look at with the key- word viewpoint. The direction of the camera will be calculated automatically. The default viewpoint is (0,0,0). 4.3.3 Aspect The camera is also defined by its x:y:z aspect, which enables you to set the pixel-aspect of the output picture and the field of view of the camera. The x:y aspect should be the same as that of the output picture. E.g. a 640x480 picture has the aspect 4:3 if the pixels are to be completely square. If the picture is to be displayed on a screen with non-square pixels (e.g. an NTSC TV) you will have to change the x:y aspect to more sutible values. The aspect ratios does not have to be integer values in RayLab. The z-aspect is the 'depth' of the lens, and it is also proporional to the x and y aspect. With the z aspect you may change the field of view. This figure may be of some help: |-- | -- Y | -- | -- Z | | +-> (+)- - - - - - - - - - + | | | | | -- | Camera location -- | X -- | --| Larger values of the z aspect will give more tele-zoom, and smaller values will give wide-angle views. Here is an example of a camera with extreme tele-zoom: Camera: location 0 -100 30 # We have to back off a bit due viewpoint 0 0 0 # to the zooming aspect 4 3 20 :end The default aspect is 4:3:5, which gives quite a normal angle of view. 4.4 Textures ------------- A good surface texture will always make an object more interesting. To add or change a texture of a primitive, add a texture-section to the primitive declar- ation. Example: Plane: normal 0 0 1 offset -2 texture: color 0.5 0.4 0.8 pattern spots reflect 0.5 0.4 0.5 phong 0.6 :end :end In the following sections all supported texture keywords will be described. 4.4.1 Color In RayLab all primitives have an own color, which can be specified by the key- word color. Following the keyword there should be three decimal values specify- ing the red, green and blue components of the color. The values can range from 0.0 (0%) to 1.0 (100%). The default color is 1.0 0.3 0.0, which is 100% red + 30% green. 4.4.2 Colormap When you want to give an object surface a pattern (e.g. the rings of a piece of wood), it is not satisfying to only have one color for the object. Normally you want to have a set of colors, and smooth transitions between those colors. This is acomplished with a colormap. A colormap sort of creates a spectrum with different colors, just like the sky can have nice transitions between red and blue and maybe some other colors when the sun sets. A colormap can consist of a maximum of ten entries. Each entry is given a color, and a place in the map. This place is a value between 0.0 and 1.0. When you declare a colormap you also have to give the amount of entries by an integer value following the keyword colormap. Here is an example of a colormap with the colors of the rainbow: colormap 7 # This colormap contains seven entries 0.0 0.4 0.0 0.7 # The first entry (at 0.0) has the color 0 0 0.9 0.3 0.0 0.0 0.9 0.4 0.0 0.4 1.0 0.6 0.0 1.0 0.0 0.75 1.0 1.0 0.0 0.9 1.0 0.0 0.0 1.0 0.4 0.0 0.0 # The last entry (at 1.0) has the color 0.4 0 0 Note: All entries must be entered in ascending order with 0.0 first and 1.0 last. Actually, when a color is specified with the color keyword, a colormap with two entries is created; the first entry is 0.0, with the color which is specified after the color keyword, and the second entry is 1.0, with the color black. This is done so that a pattern will be visible even if only one color is speci- fied. This means that the default colormap has two entries: the first is red and the second is black. 4.4.3 Pattern Patterns can significantly improve the appearance of an object. RayLab gives you a variety of patterns to chose from, and more are sure to come. A pattern will assign a value to each point of the object. This value ranges from 0.0 to 1.0 and is used as index to the colormap of the object. Now follows a descript- ion of the currently available patterns in RayLab. Experiment with them on different shapes to get to know how they work! 4.4.3.1 checker Now this is a pattern we all want! A raytracer is not worth the name without this pattern. The checker pattern is simply an infinite amount of 1x1x1 cubes in 3D space. If applied to a plane it will look just like a chess-board, but if you apply it to a sphere it can look rather strange (try it, and you will see exactly how it works!). Each checker can have one of two colors, and the color is chosen from the colormap of the object. The first color is picked from the colormap with index 0.0, and the second will be picked with index 1.0. Here is an example of a blue and green checkered texture: texture: pattern checker colormap 2 0 0 0 1 1 0 1 0 :end 4.4.3.2 circles Circles are like onion-rings. The colormap index is simply proportional to the distance from (0,0,0). Within one unit-distance the index-value changes from 0.0 to 1.0, then it goes back to 0.0 and increaces to 1.0 at two units, and then it starts over again... 4.4.3.3 rings The rings pattern works like circles, but it only depends on the x-y coordi- nates. This means that it extend along the z-axis, and is very well suited for wooden textures. 4.4.3.4 spots The spots pattern will simply produce spots on the surface of the object. The centre of the spot will get the color from the colormap at 0.0. The further away from the centre of the spot, the larger the colormap index. At the edge of the spot, and outside of the spot, the colormap index is 1.0. 4.4.3.5 gradient This is probably the simplest pattern possible. The colormap index changes with the z-axis. It increases from 0.0 to 1.0 within one unit along the z-axis, then it starts over from 0.0 again... 4.4.3.6 none Specifying a pattern with the identifyer none will give the object a mono- colored surface. The color will be picked from the colormap with index 0.0. The default pattern is none. 4.4.4 Reflect Reflection is one of the most interesting and powerful featurs of the ray- tracing technique compared to other forms of 3D rendering. In RayLab you can chose how much light an object should reflect. You can also decide what colors will be reflected. Here is an example of a reflection that reflects 70% of all light: reflect 0.7 0.7 0.7 # red=70%, green=70%, blue=70% The default reflection is no reflection att all (0 0 0). 4.4.5 Diffuse The diffuse keyword specifies how much of the light from the surrounding light- sources will affect the color intensity of the object. The diffuse intensity is specified by a decimal value ranging from 0.0 to 1.0. If a value of zero is given, the object will have the same color intensity on its lightened side as on its shadowed side. Normally, you would want a value between 0.5 and 1.0. The default diffuse intensity is 0.8. 4.4.6 Ambient If you look around in "the real world" you will see that even in the darkest shadows, objects are visible. This is due to the diffuse reflection from other surrounding objects. In a normal raytracer like RayLab, this is a very diffi- cult and power consuming task to produce. Instead this is simulated by the ambient effect, which will give the object a default light-intensity on every point of the surface. The ambient effect can also be used to create "glowing" objects. However, the ambient of one object will not affect any other objects. The keyword ambient is followed by a decimal value ranging from 0.0 to 1.0. The default ambient is 0.2. 4.4.7 Phong The phong keyword specifies how intense highlights from light-sources should be. Phong highlights have the same color as the light-source that it is prod- uced from, and is not proportional to the object color at all (a black object will have the same highlight color and intensity as a green object). The default phong value is 0.3. 4.4.8 Phongsize With phongsize you can specify the tighness of the phong highlight. The key- word is followed by a positive decimal value. Higher values give tighter spots. Theoretically the phongsize value can range from zero to the infinity, but in practice you would typically want a value larger than 1.0 (at least) and smaller than 100. The default phongsize is 10.0. 4.4.9 Default The keyword default can be placed in a texture section to initialize the texture with RayLabs hardcoded default settings. 4.5 Deftexture -------------- With a deftexture section, you can specify a default texture that will be applied to all the following objects in the scene description. Example: Deftexture: reflect 0.6 0.6 0.6 pattern spots colormap 4 0.0 1 0 0 0.7 1 0 0 0.8 0.2 0.2 0.2 1.0 0 0 0 :end At the end of the list of all objects that are to have the texture specified by deftexture, you will probably want to reinitiate the hardcoded default texture. Simply write: Deftexture: default :end 4.6 Transform ------------- When the shape of a primitve is too limited for your demands, chanses are that the transformation facilities of RayLab can help you. Transformations can change the shape, locaion and orientation of any primitive or texture. There are currently three possible transformations available in RayLab: scale, move and rotate. A transform section can contain a maximum of ten transformations, which are applied to the object or texture in the order they are entered in the description. A transform section is started with the transform keyword, and ended with ':end'. Here is an example: transform: rotate 30 0 0 # rotate 30 degrees around the x-axis scale 3 0.6 1 # scale 3*x, 0.6*y and 1*z move -3 0 4 # move the object -3*x +4*z from its current :end # location Note that the following exaple will NOT do the same thing as the above: transform: move -3 0 4 rotate 30 0 0 scale 3 0.6 1 :end 4.6.1 Scale Scaling an object means stretching or shrinking it along the x, y and z axis respectively. A scale value of 1.0 means no change. A value >1.0 means stretch- ing and a value <1.0 means shrinking. One value must be given for each dir- ection (i.e. three decimal values must follow the scale keyword). The scaling is always done relative to (0,0,0) in space, so if you scale a primitive that has an origin different from (0,0,0), it will also be moved. 4.6.2 Move Moving an object means moving it from its current location to a location given by (current location) + (movement). Also here three decimal values must be given after the keyword. 4.6.3 Rotate After the rotate keyword you must specify three angles (in degrees). They represent the rotation around each of the x, y and z axis, and the rotation is performed in that order (first x, then y and last z). To find out which way is the positive rotation, try this trick: hold up your right hand in front of you, extend your thumb and curl the other fingers. Now, if you place your hand so that the thumb points in the positive direction of the axis that you want to rotate about, the four fingers will show the positive direction of rotation. Remember that RayLab uses a right hand system, so the orientation of the axises is as follows: the x-axis points right, the y-axis points "away", and the z- axis points up. An object or a texture is always rotated around (0,0,0) in space, so if you rotate a primitive that has an origin different from (0,0,0), it will also be moved. 4.6.4 None The keyword none will clear a whole transform sequence. The default transformation is no transformation. All transformations that can be done to an object, can also be done to a texture, independently. Often you may want to change the size or orientation of a pattern. To transform a texture, enter a transform section to the texture section. This example shows how you can make a pattern twice its original size: texture: pattern checker colormap 2 0 1 1 1 1 0 0 0 transform: scale 2 2 2 :end :end 4.7 Deftransform ---------------- With a deftransform section, you can specify a default transformation sequence that will be applied to all the following objects and textures in the scene description. Example: Deftransform: rotate 30 -45 17 move 10 0 -5 :end At the end of the list of all objects that are to be transformed with a def- transform, you need to withdraw the deftransform. Simply write: Deftransform: none :end 4.8 Globals ------------ In RayLab some interesting and useful parameters can be setup in a section called globals. 4.8.1 Picwidth The keyword picwidth is followed by an integer value telling RayLab how many columns the output picture will have. For a 640x480 image this would be 640. The default picture width is 200. 4.8.2 Picheight Picheight specifies the amount of lines that the output image will consist of. The default picture height is 150. 4.8.3 Backgroundcolor You can specify a color that will be the background color of your scene. For instance this can be very useful if you make an outdoor scene where you want the sky to be blue; simply set the background color to blue. Backgroundcolor is followed by three decimal values ranging from 0.0 (0%) to 1.0 (100%), each value representing the red, green and blue components of the color, respect- ively, in that order. Example: bacgroundcolor 0.3 0.0 0.0 # Dark red sky The default color is 0 0 0 (black). 4.8.4 Recdepth The keyword recdepth is used to specify how many recursions RayLab is allowed to do for each camera-ray. A recursion-depth of 2 means that a ray will only 'bounce' one time through reflection, and a recursion-depth of 1 results in no reflection at all. Higher values means more realistic pictures, but also longer rendering-times if there are many reflective objects in the scene. Example: recdepth 4 The default recursion depth is 3. 4.8.5 Display If you want to view a picture as it is being rendered, add the keyword display to your globals section. Following the keyword you must specify a display type. The display types are machine specific, so please consult the documentation for your specific platform for more information. The display type is an integer value. Example: display 1 Zero (0) means no display, which is the default. 4.8.6 Antialiasrec This keyword turns on antialiasing, which can greatly improve the appearance of a scene. You must specify the recursion depth of the antialiasing, which is done with an integer value placed after the keyword. Example: antialiasrec 3 Zero (0) means no antialiasing, which is the default. The recursion level can range from 0 (no antialiasing) to 4 (extremely heavy antialiasing). A value of 2 or 3 should be enought in most cases. Never use a recursion level of 1 though, as it is totally useless (it just blurs the picture, even turning antialiasing off looks better). For the different recursion levels, this is the maximum amount of rays that are traced for each pixel: Level: Rays: 0 1 1 4 2 9 3 25 4 81 Well, RayLab uses a very intelligent adaptive method (meaning it does not have to trace more rays than really necessary), so in reality only one to six rays have to be traced per pixel if there are not too many edges and contours in the picture. 4.8.7 Antialiasthreshold As mentioned, RayLab uses an adaptive method for antialiasing. This is achived by comparing the colors from the four corners of a square (this square is in reality a pixel from the picture). If the difference between the colors are not too big, it is assumed that this entire square has the same color (which is the average of the four colors). If the difference exceeds a certain value, the first square is divided into four new squares, which are checked in the same manner. With antialiasthreshold you can specify the threshold for how big the difference between the colors may be before another recursion takes place. The value specified after the keyword must be a decimal value ranging from 0.0 (all rays are casted as specified by the antialiasing recursion level) to 3.0 (no squares are subdivided). Example: antialiasthreshold 0.4 The color difference is calculated as the sum of the maximum red, green and blue differences. The default value is 0.3, which seems to be a very good value (you may raise this if you need faster rendering). 4.9 Comments ------------- In RayLab scene descritions you can put comments to clarify your work, both to yourself and others. A comment can be placed anywhere, except in the middle of or right after (no space, tab or newline between) a keyword or a number. Every comment is started by a comment identifyer and it is ended by the end of the line. The comment identifiers are # ; and * Example: Sphere: # This is a sphere centre 0 0 0 ; and it is placed in (0,0,0) radius ****** ok, here comes the radius: 2 :end As you see, it is fully possible to put a comment between the keyword and its parameter(s), although it does not look very nice. 5. MISCELLANEOUS ================= 5.1 How to contact the author ------------------------------ I always like to get response from people who somehow come across my work, be it good or be it bad. So if you have used RayLab, read the documentation or heard about my latest assembler program for the C=64, please drop a mail in my e-box: internet: e4geeln@etek.chalmers.se If you get any error-messages when compiling RayLab on your system, please let me know as it would be nice to have it compile flawlessly on as many systems as possible. Do not hesitate to report things like "strings.h not found..." (it worked fine on my Amiga and at the university, but not at a friends PC with an old Microsoft compiler. Now I know it should be string.h!!). Any bug-reports etc. will ofcourse be warmly welcomed. If you do not have access to internet, you can contact me by snail-mail: s-mail: Marcus Geelnard Utbynasgatan 11 S-415 06 Goteborg Sweden 5.2 Legal stuff ---------------- I have not yet decided exactly how I want RayLab to be released to the public, but as I want to start distribution as soon as possible, I chosed to make the restrictions a bit tight until I have made up my mind. Please let me know if you have any preference/opinion about how RayLab should be treated legally. Anyway, here are the rules: o RayLab is provided as is, and the author can not be held responsible for any system failure or data loss as a result, direct or indirect, of the use of RayLab. Use RayLab at your own risk. o RayLab is totally free! You should not pay a penny for the actual software, nor can anybody claim any money for RayLab (except for formal fees for storage media or transfer costs). o You may NOT change RayLab in part or in whole, and then redistribute it! The files and the contents of the files must remain as is, and they must all be there with their original names and in their original directory structures! o You may NOT use any part(s) of the RayLab sourcecode for your own product- ions, neither commercial nor noncommercial! o If you want to use RayLab or any pictures that are produced with RayLab for commercial purposes, you will have to have the permission to do so from the author of RayLab. o For noncommercial use of RayLab, such as a private art-gallery, you need no permission from the author of RayLab. o You may NOT spread your own compilation of RayLab without permission from the author of RayLab! If you feel like breaking any of the above stated rules, e.g. if you want to improve RayLab, try contacting me (the author of RayLab) first. I am not un- reasonable, but I do like to have some control of my own software. 5.3 Past, present and the future --------------------------------- Since the first release (1.0), these changes/additions have been made: o The disc primitive was added. o The cylinder primitve was added. o Anti-aliasing was added. o Display support for the Amiga was added. o A minor bug in the memory handling was detected and eliminated. o Some minor changes and improvements to the code have been made. Right now RayLab is in a premeture stage, where I expect to find many bugs, and lots of things remain to be improved and implemented. Things that will most certainly be implemented in RayLab in a relatively near future (?): o Transparency and refraction. o More patterns. o Better description language, especially more abstractions and better handling of faulty descriptions. Things that I would like to implement in RayLab, but I don't know when, or even if, it will be: o Focus blur. o Pattern distortion for more realistic appearance. o Surface normal modifiers, like bumpiness and waves. o Animation support, which will probably consist of a good expression handler and some useful mathematical functions like sin(x), sqrt(x), log(x) etc. o Motion blur (based on the animation support). Any further suggestions are ofcourse welcome... 5.4 Comments by the author --------------------------- I admit that RayLab was influenced by other raytracers that I have used (POV- Ray, Imagine and Rayshade), but that is mostly due to my finding parts of those raytracers very natural. I did, however, start from scratch when I developed RayLab, and the only thing I have looked at from other source codes (so far) is the C-language itself (I am still a beginner). The combination of RayLab beeing one of my first C-programs, and me not having any experience in ray- tracing techniques (except for the actual usage of other raytracers) is one reason why RayLab is quite slow, and also I guess the source code itself looks rather nasty (? still better than assembler though). And then we have the description language... It is very primitive and not very fault-tolerant right now, but I do have major plans (hrrm) for future improve- ments. You may wonder what the START/END keywords under the cylinder declaration are doing (in 'getworld.c'). Well, my primary intention with the cylinder was to have it declared by its both ends in space and its radius, but as for now I had to settle for a simpler solution. The discs at the ends of the cylinder are actually correct in respect to the START/END statements, but the cylinder body is not, so it will look rather peculiar if you define ends that do not lay along the z-axis, I guess. Many of the things that are declared in a globals section should be possible to declare right at the command line when calling RayLab, but so far I have not decided how the parameters should look (and I AM lazy!). Pheew! This documentation got a bit larger than expected... This program was intended to be a simple personal hack, not a commercial raytracer!