RoughRay Help Contents

The user interface for RoughRay is simple yet usable. You load, save and edit text files as you would in any other application. The .RRY scripts describe a 3 dimensional scene which is then drawn on the desktop.

.RRY Script

RoughRay saves text files with a .RRY extension. The script is parsed into tokens without regard to case. Tokens are delimitted by white space which includes 'space', 'tab', 'comma', '{' and carriage return. No white space is allowed within tokens or names. An underscore is used to seperate words in tokens. File names must be in "double quotes". Single line comments are denoted by beginning the comment with a semi-colon. Multi-line comments are enclosed in brackets. The script is seperated into logical blocks that are started with the name of the block and ended with "end_NameOfBlock" or " }". These blocks are described below. These blocks contain members, most of which have default values and can be excluded. An outline of a script looks like this:
() are used to denote optional blocks.
(;a comment about the file including the author and what the heck it is supposed to look like!)
(animation ... end_animation)
(tracer ... end_tracer)
(define ... end define) ;reusable objects defined here
(interpolation ... end_interpolation) ;lists of named values that change over time for animation
scene
	camera ... end_camera 
	light ... end_light
	(loop ...
		(frame
			(camera ... end_camera) ;there can only be one camera but it may be placed within a frame
			(light ... end light)   ;there can be many lights - slows rendering
			(intersection
				(cube 
					(rotate translate scale)
					(material ... end_material)
				(end_cube)
				(sphere ... end sphere)
			end_intersection)
		end_frame)
	end_loop)
end_scene

3 Dimensional Space

3 dimensional space is represented by x,y,z coordinates. Depending on the positioning of the camera these coordinates are interchangeable. With a Camera at 0,0,2 looking at a screen at 0,0,1 the dimensions equal x=right, y=up, z=forward. You position objects by declaring a Matrix included in a Frame or by using the Rotate, Scale and Translate fields of an object.
Translate x,y,z specifies a positioning in space.
Scale x,y,z specifies a scaling in width, height and depth with 1 equalling no scaling.
Rotate x,y,z specifies a pitch, yaw and roll in radians.
Each matrix operation is performed as a child of the last. Rotating and then translating means the translation will be rotated.

Animation

Animations string together multiple images into a video file. To animate geometry you use Interpolation and Functions of time.
Parent: Root of Document

Camera

The camera describes how rays are cast into the scene. They originate from the camera's translation and pass through each point of the screen. If they bounce off an object they are illuminated by the light reaching that object.
Parent: Scene or Frame

Cone

Imagine x=y rotated about the y axis. That's a cone. It is a basic shape located at the origin so it uses it's own matrix for positioning.
Parent: Scene or Frame

Constructive Solid Geometry

CSG is used to build complex objects from simple ones. These are implemented by testing whether a ray intersects a parent and a child object and then performing a logical operation on these boolean values. Even though each CSG only operates on two objects the parent and child can also be CSG objects with "unlimited" nesting. The implementation currently only holds the first entrance and last exit points of the ray as it passing through the object. Concave CSG objects with transparency will not properly display child objects inside of them. Efforts have been made to make single sided objects like a plane useful in CSG by creating an "infinite" back face. This implementation may cause unexpected results.

Cube

Cube specifies a 2x2x2 box about the origin.
Parent: Scene or Frame

Cylinder

Cylinder specifies a one unit tall capped cylinder.
Parent: Scene or Frame

Cosine

Cosine graphs the function y=cos(r) where r is the distance from the origin.
Parent: Scene or Frame

Define

Define can be used to reduce the amount of typing and text stored. If an object will be reused wrap it inside a define then use Include to paste the text into the Scene. You can only use Define for storing objects not object members ie. float values.
Parent: Root of Document, Scene or Frame
Notes: You must end the define with "end_define" not "}". The shorthand is disabled for obvious reasons. Hence you cannot nest Defines. The script is inserted just prior to parsing with no regard as to the context of the Define. For example a sphere defined in one Frame but used in another will be effected by the later.

Difference

Difference is a Constructive Solid Geometry object created from the logical NOT of two objects. Think of it as the subtraction of the second object from the first. Not associative! Note: The material definition must come before the parent and child to be useful. Otherwise if the parent or child do not contain their own material definition they will inherit the last material defined.

Everywhere

Everywhere is an object that incompasses all the space. It is only of value as the parent in the Difference CSG object. It results in the inverse of the child object.
Parent: Difference There are no fields to specify with this object.
Example: Creating a sky dome. 
difference
	everywhere { }
	sphere { scale 100,100,100 }
end_difference

Frame

A Frame is used to connect objects in a Parent, Child relationship and to group objects into more complex structures with joints. The Frame holds a single Matrix, multiple objects and child frames.
Parent: Scene or Frame

Functions

A fair number of intrinsic functions are defined for use in place of float values. These include:
FunctionMeaningArguments
addAddition2
subSubtraction2
mulMultiplication2
divDivision2
flrFloor (next integer lower)1
clgCeiling (next integer higher)1
maxMaximum2
minMinimum2
absAbsolute (remove sign)1
modModulation (remainder as integer)2
powValue raised to Power2
logLogarithm1
expExponent1
sinSine1
cosCosine1
tanTangent1
asnArcsine1
acsArcosine1
atnArctangent2
rndRandom0
equEquals2
gtGreater Than2
ltLess Than2
neqNot Equal2
ifeIf Equal Else3
andLogical And2
orLogical Or2
notLogical Not1
timeTime as indicated in Animation0

No parenthesis are used. Calculation is always performed right to left. Use these functions to manipulate float values based on the time value in Animations, Interpolated values (also based on time) and in Loop statements to compare and use the counter value.
Example: Positioning an object based on the division of time by the larger of the Sine and Cosine of time.
Cube
	Translate 0,0,div time, max sin time, cos time
End_Cube

We need not worry about division by zero as a replacement small value will be used.

Height_Map

A height map uses a Bitmap picture file (.bmp) with color intensities representing heights. The mapping function looks like this: x=px/pwidth-0.5,y=colorrgb/maxrgb,z=py/pheight-0.5
This returns a unit cube centered at the origin with its top shaped to the color intensities.

Hyperboloid

The Hyperboloid is a hyperbola rotated around y. Parent: Scene or Frame

Include

Include is used to insert text from another file or a previous Define. This text is then parsed as if it were typed at the position of the include statement. Note: Use either Name or File, not both. Parsing errors in the inserted text will not be selected.

Interpolation

Interpolation creates a sliding scale of values used in Animation. The values are given in vector2 pairs. The first value is the animation time determined by the formula: start_time + current_frame*(end_time-start_time)/total_frames
The second value is a float. When the parser sees the name of the interpolation where a float should be it substitutes a value calculated from the interpolation list. Example: If you want an object to move through the scene during an animation you could use...
interpolation
	name interp01
	0.0 -10.0
	1.0 10.0
end_interpolation
cone translate interp01,0,0 end_cone

Intersection

Intersection is a Constructive Solid Geometry object created from the logical AND of two objects. The resultant object will contain only the portion included in both objects. Note: The material definition must come before the parent and child to be useful. Otherwise if the parent or child do not contain their own material definition they will inherit the last material defined.

Light

Any number of lights are permitted to illuminate the Scene.
Parent: Scene or Frame

Loop

Loops allow for programatically creating objects. You give the loop a name which becomes a loop counter starting at zero. It then performs a logical test with a function of that value and repeats the body of the loop until the test fails.
Parent: Scene
Example: Creating a horizontal row of 10 spheres 
loop my_loop 
	lt my_loop, 10
	sphere { translate my_loop,0,0 }
end_loop

Material

A Material gives an object a certain "look". It may optionally include a Texture file which will be stretched over the object. When an object is specified without a material the last material parsed will be used. A default White material is pre-loaded into the parser.
Parent: Object, Frame or Scene
  • Name (unique token) allows reusing the material which is important with texture files.
  • Diffuse (vector3) the Red, Green and Blue components of the base color.
  • Transparency (float) the amount of transparency.
  • Inner_Transparency_Depth (float) how deep into the object light gets before being diffused.
  • Gloss (float) the amount of polish when highlighting.
  • Reflection (float) the amount of light reflected off the surface of the object.
  • Refraction (float) the amount of bend when light travels through an object.
  • Density (float) the number of times the texture is repeated over one unit. Default 1.0
  • Texture_File (double quoted string) complete path and file name. Must be a bitmap .bmp file.

Example: If you want to reuse a material with texture name it and then recall the name.
material name test
	texture_file "c:/test.bmp"
end_material	
cube
	material diffuse 1,0,0 end_material
end_cube
sphere
	position 1,0,0
	material name test end_material
end sphere

Matrix

Matrix math is used to position the objects in 3d space. Luckily you don't need to do the calulations yourself. You can use the Translate, Scale and Rotate fields of an object or frame. You may also explicitly define the matrix in a Frame. A matrix is a 4x4 grid that holds all the information for determining the size, orientation and position of an object. Here is how a matrix is put together:
Right.x*Scale.xUp.x-Forward.x0
Right.yUp.y*Scale.y-Forward.y0
Right.zUp.z-Forward.z*Scale.z0
Translate.xTranslate.yTranslate.z0
It may look complicated but if you leave scaling out and picture Right, Up and Forward as normal vectors determining the directions of x,y and z respectively it isn't to difficult to create one yourself.
Example: Say you want to deform an object by pulling the dimension Right towards the dimension Up and move it up. 
frame
	matrix
1-time
0
0
0
time
1
0
0
0
0
1
0
0
time
0
1
	cube end_cube
end_frame

Mesh

A Mesh is a series of triangle faces used to approximate a complex surface. Each triangle is described by three vertices. Each vertice consists of a position vector, normal vector and a texture coordinate. The normal vector is used when lighting and reflecting off the surface. It is a vector with length equal to 1 perpendicular to the surface. The texture coordinate is used with Materials that have a texture file specified. It describes how the texture is mapped to the triangle. The texture coordinate 0,0 means the upper left hand pixel will be used.
Parent: Scene or Frame

Paraboloid

The Paraboloid is a parabola rotated around y. Parent: Scene or Frame

Plane

Plane specifies a flat horizontal surface with y=0. Use the Matrix manipulating fields to reorient the default ground plane into a wall etc.
Parent: Scene or Frame

Quadric

Quadric specifies a curved shape generated from an expression in the form:
ax^2+by^2+cz^2+dxy+exz+fyz+gx+hy+iz+j=0
Parent: Scene or Frame
Example: Say you want to create a unit sphere that distorts diagonally through xy. The formula for a sphere is x^2+y^2+z^2-r^2=0. To change the radius (r) we change the coefficient j. To position the sphere we change the coefficients g,h and i. To distort it over a plane we change d,e and f. The coefficients a,b and c change the direction of the curve.
quadric
	cooefficients 1,1,1,time,0,0,0,0,0,-1
end_quadric

Scene

The Scene holds the camera, all the lights and geometry to be traced. It also holds a few key properties...
Parent:Root of Document

Surface of Revolution

The SOR is a list of 2D vectors whose x,y coordinates draw the outline of a curve that will be rotated about y. Parent: Scene, Frame

Sphere

The Sphere is a circle rotated around y. Parent: Scene, Frame or CSG

Tracer

The Tracer holds commands for the trace engine about how to create the image(s).
Parent:Root of Document
  • Width (integer) The width of the resultant image in pixels.
  • Height (integer) The height of the image in pixels.
  • Max_Depth (integer) The depth of recursion allowed when bouncing rays off or through objects.
  • Antialiasing (integer) The number of extra pixels to average into the image to remove artifacts.
  • No_Diffuse Indicates no diffuse coloring.
  • No_Highlights Do not perform phong highlighting.
  • No_Shadows Do not create shadows.
  • No_Reflection Do not reflect light off objects.
  • No_Refraction Do not refract light through objects.

Union

Union is a Constructive Solid Geometry object created from the logical OR of two objects. Think of it as the addition of the second object to the first. Associative! Note: The material definition must come before the parent and child to be useful. Otherwise if the parent or child do not contain their own material definition they will inherit the last material defined.

Tutorial

Let's walk through the features of RoughRay by starting with a minimal Scene. Every Script needs a Scene element to encompass all the geometry and we will need at least one object if we want anything to be drawn.
scene
	cone { translate 0,0,3 }
end_scene

Copy the text above into the text area of RoughRay and click Play. You should see a flat looking cone drawn. Not too impressive yet. We need to add a light to get a 3-Dimensional feel.
scene
	light { translate 10,0,10 color 1,1,1 strength 100 } ;the new line
	cone { translate 0,0,3 }
end_scene

Before we go too far we should define our camera. There can only be one camera and so far we have just used the default. If you declare multiple cameras only the last one will be used. We will move the camera away from the origin and place our object at the origin.
scene
	camera { translate 0,0,2 look_at 0,0,0 } ;the new line
	light { translate 10,0,10 color 1,1,1 strength 100 } 
	cone { }
end_scene

Our scene is still not very interesting. We will put in a couple more objects to see shadows and reflections form.
scene
	camera { translate 0,0,2 look_at 0,0,0 }
	light { translate 10,10,10 color 1,1,1 strength 100 } 
	cone { }
	plane { translate 0,-1,0 material { diffuse 0,1,0 } } ;a new line, some green grass
	sphere { translate 1,0,-1 material { reflection 1 } } ;a new line, a chrome ball
end_scene

You will see in the shadows that some pixels appear rough. That is called aliasing. We can tell the ray tracer to add antialiasing and change the size of the image by putting in a Tracer section.
tracer
	antialiasing 8 ;how many times to recalculate each pixel (add jitter and average)
	max_depth 10   ;how many reflections and refractions are allowed 
	width 512
	height 512
end_tracer
scene ;... this would be the same as the text above

Now lets change some positions and try refraction (the way light bends as it passes through an object).
scene
	camera { translate 0,0,3 look_at 0,0,0 } ;we moved the camera back
	light { translate 10,10,10 color 1,1,1 strength 100 } 
	cone { }
	plane { translate 0,-1,0 material { diffuse 0,1,0 } }
	sphere { translate 0.5,0,1 material { transparency 1.0 refraction 0.6 } } ;we move the sphere in front and made it transparent
end_scene


So far we have played with the Diffuse, Reflection, Transparency and Refraction properties of a Material. There are a couple more we need to understand. Gloss adds phong highlighting (a higher number creates a tighter highlight) and Texture_File which paints the surface with an image from a Bitmap picture file. We will add them in and see how the picture changes.
scene
	background_color 0,0,0 ;this sets the color of the background
	camera { translate 0,0,3 look_at 0,0,0 }
	light { translate 10,10,10 color 1,1,1 strength 100 } 
	cone { }
	plane { translate 0,-1,0 material { diffuse 0,1,0 texture_file "castleFloor.bmp" } }
	;smaller gloss values make the object appear slightly scuffed
	sphere { translate 0.5,0,1 material { gloss 0.1 transparency 1.0 refraction 0.6 } }
end_scene

Notice how the refracted image is upside down. We can change this by making a simple lens using the Difference CSG object in place of the sphere. Here we cut a second sphere from the first making a concave lens.
difference
	material { transparency 1.0 refraction 0.6 } 
	sphere { translate 0.5,0,1 }
	sphere { translate 0.5,0,1.1 }
end_difference








  • 

  •