The RAY file format has been specially modified to suit the needs of CS155, for use with the ray tracer project. This specification corresponds to the accepted file format for rt, the example raytracer developed for this class. It's basic format is a list of directives, denoted by hashes (#), followed by the necessary data for the directive. C and C++ style comments are allowed anywhere within the file. The beginning of a RAY file is denoted by the #version directive and the end is the #rayfile_end directive.

Conventions

A directive is a single string (no whitespace) beginning with a hash mark. Flags, if accepted by the directive, follow immediately and are concluded with a double-hyphen '--'. A directive that accepts flags must have the concluding double-hyphen even if flags are not used. Finally the directive arguments are provided. Whitespace is ignored, so place spaces, tabs, newlines, etc. wherever you like.

Comments may appear at any point in the file. There are two types of comments: line comments and block comments. A line comment starts with a // and continues to the end of the line. A block comment starts with a /* and continues until a */ is encountered. Nested block comments are not allowed and will result in a parse warning. There must be whitespace around the comment tokens (// /* and */) for the comments to be properly parsed. If there isn't, such as int i = 0;// initialize i, the // will be missed and parsing will fail.

All angles are specified in degrees.

Directives

#version HMCCS155FALL2002 or
#version HMCCS155FALL2005

The version directive starts the rayfile. The string following it is the version of the RAY file. We currently support the two version numbers shown above.

#rayfile_end

The rayfile_end directive ends the rayfile. This directive isn't necessary, but can be useful if you need to embed a rayfile in a text stream (such as an email message).

#background r g b

The background directive specifies the color to use when raytracing, in the event that a ray doesn't intersect with any objects. It is followed by an RGB triplet (range [0..1]).

#ambient ar ag ab

The ambient directive specifies the color and intensity of ambient lighting in the scene. It is followed by an RGB triplet (range [0..1]).

#camera
    px py pz    // position
    tx ty tz    // toward
    ux uy uz    // up
    theta       // half height angle in degrees

The camera directive specifies the default view point in the scene. The first triplet is the position of the camera, followed by the direction the camera is facing, the up vector, and finally an angle in degrees representing half of the height view angle.

#light_dir [ -n name ] --
    lr  lg  lb     // color
    ldx ldy ldz    // direction

The light_dir directive adds a directional light to the scene. It has an optional name flag (useful for debugging), followed by a '--' to mark the end of the flags. The RGB triplet specifies the color of the light and the second triplet is the direction the light points.

#light_point [ -n name ] --
    lr  lg  lb     // color
    lpx lpy lpz    // position
    ca  la  qa     // const linear quad attenuation

The light_point directive adds a point light to the scene. It has an optional name flag (useful for debugging), followed by a '--' to mark the end of the flags. The RGB triplet specifies the color of the light, the second triplet is the position of the light, and the last three values are the constant, linear and quadratic attentuation factors (use 1 0 0 for no attenuation).

#light_spot [ -n name ] --
    lr  lg  lb     // color
    lpx lpy lpz    // position
    ldx ldy ldz    // direction
    ca  la  qa     // const linear quad attenuation
    co  do         // cutoff angle, dropoff rate

The light_spot directive adds a spot light to the scene. It has an optional name flag (useful for debugging), followed by a '--' to mark the end of the flags. The RGB triplet specifies the color of the light, the second triplet is the position of the light, the third triplet is the direction the light is facing, the fourth triplet is the constant, linear and quadratic attentuation factors (use 1 0 0 for no attenuation). The last two values are the cutoff angle, in degrees, which represents half the angle of the spotlight's cone of light, and the dropoff rate (range [0,1]) which represents how quickly the intensity falls off from the center of the spotlight.

#material -n name [ -t texture file ] [ -u bump map file ] --

    mar mag mab    // ambient response
    mdr mdg mdb    // diffuse response
    msr msg msb    // specular response
    mer meg meb    // emissive color
    ks  kt  rf     // kspec, ktrans, refractive index

The material directive specifies a set of surface properties to use for calculating the color of an object. It has a required name flag (used by objects to specify their material), an optional texture file flag (path relative to the RAY file), and an optional bump map file flag (path relative to the RAY file). These are followed by a '--' to mark the end of the flags. The first RGB triplet is the material's response to ambient light. The second is the response to diffuse light, the third is the response to specular light, and the fourth is the light the material emmits. The last three values are the kspec or shininess coefficient (range [0,1], 0 is matte and 1 is most shiny), the transparency coefficient (range [0..1], 0 is opaque, 1 is perfectly transparent), and the refractive index (which is at least 1.0; e.g. 1.0 is air, 1.52 is glass).

#sphere -m material [ -n name ] [ -t ] [ -u scale ] --
    cx cy cz    // center position
    r           // radius

The sphere directive creates a sphere shape in the scene. It has a required material flag (with the name of the desired material as the argument), followed by an optional name flag (useful for debugging), an optional textured flag (if present, the sphere is texture mapped, otherwise no texture mapping is done), an optional bump-mapping flag (if present, the sphere is bump-mapped) with a scaling factor to apply when bump-mapping, and finally the '--' to mark the end of the flags. Next comes the XYZ coordinates of the sphere's center, and finally the sphere's radius.

#triangle -m material [ -n name ] [ -t ] [ -u scale ] --
    v0x v0y v0z  [ t0s t0t ]    // vertex 0  [ texcoord 0 ]
    v1x v1y v1z  [ t1s t1t ]    // vertex 1  [ texcoord 1 ]
    v2x v2y v2z  [ t2s t2t ]    // vertex 2  [ texcoord 2 ]

The triangle directive creates a flat triangle shape in the scene. It has a required material flag (with the name of the desired material as the argument), followed by an optional name flag (useful for debugging), and optional flags for texturing and bump-mapping (which must also have a specified scale). (If any is present, the texture coordinates must be specified with the vertex coordinates; otherwise, texture coordinates must not be specified with the vertex coordinates), and finally the '--' to mark the end of the flags. Next come the XYZ coordinates (and UV texture coordinates, if the -t or -u flag is present) of each of the three vertices in the triangle.

Note: Normals point in the CCW direction, so specify your vertices counter-clockwise to orient the normal appropriately. OpenGL mode by default does not backface cull - turn it on via the menu to see which direction your triangle normals point.

#cylinder -m material [ -n name ] [ -t ] [ -c ] [ -r ]  [ -x ] [ -u scale ]--
    cx cy cz    // base center
    r  l        // radius, length

The cylinder directive creates a cylinder shape in the scene, aligned with the z-axis. It has a required material flag (with the name of the desired material as the argument), an optional name flag (useful for debugging), an optional textured flag (if present, the cylinder is texture mapped), an optional closed flag (if present, the cylinder has endcaps), and an optional bump-mapping flag (if present, the sphere is bump-mapped) with a scaling factor to apply when bump-mapping, followed by the '--' to mark the end of the flags. The XYZ triplet specifies the center of the base of the cylinder, r is the radius and l is the length from end to end.

#cone -m material [ -n name ] [ -t ] [ -c ] [ -r ]  [ -x ] [ -u scale ]--
    cx cy cz    // base center
    r  l        // base radius, length

The cone directive creates a cone shape in the scene, aligned with the z-axis with the base at the origin. It has a required material flag (with the name of the desired material as the argument), an optional name flag (useful for debugging), an optional textured flag (if present, the cone is texture mapped), an optional closed flag (if present, the cone has endcaps), and an optional bump-mapping flag (if present, the cone is bump-mapped) with a scaling factor to apply when bump-mapping, followed by the '--' to mark the end of the flags. The XYZ triplet specifies the center of the base of the cone, r is the radius at the base, and l is the length from base to apex.

#torus -m material [ -n name ] [ -t ] [ -r ] [ -x ] [ -u scale ]--
    cx cy cz    // center
    r1 r2       // major radius, minor radius

The torus directive creates a torus shape in the scene, in the XY plane. It has a required material flag (with the name of the desired material as the argument), an optional name flag (useful for debugging), an optional textured flag (if present, the torus is texture mapped), and an optional transparency mapping flag (if present, the torus will use transparency mapping), an optional cutout mapping flag (if present, the sphere uses a cutout map), --> and an optional bump-mapping flag (if present, the torus is bump-mapped) with a scaling factor to apply when bump-mapping, followed by the '--' to mark the end of the flags. The XYZ triplet specifies the center of the torus. The major radius is the distance from the center to the circular axis of of the cylinder, and the minor radius is the radius of the cylinder.

#box -m material [ -n name ] [ -t ] [ -r ] [ -x ] [ -u scale ]--
    cx cy cz    // center
    sx sy sz    // size

The box directive creates an axis-aligned box shape in the scene. It has a required material flag (with the name of the desired material as the argument), an optional name flag (useful for debugging), an optional textured flag (if present, the box is texture mapped), and an optional bump-mapping flag (if present, the sphere is bump-mapped) with a scaling factor to apply when bump-mapping, followed by the '--' to mark the end of the flags. The first XYZ triplet specifies the center of the box, and the second is the size of the box in each direction.

#group_begin [ -n name ] --
    m11 m12 m13 m14
    m21 m22 m23 m24
    m31 m32 m33 m34
    m41 m42 m43 m44
    ...shape directives...
#group_end

#group_begin  [-n name] --
...transform directives ...
...shape directives ...
#group_end

The group_begin directive marks the beginning of a group of shapes in the scene. It has an optional name flag (useful for debugging), followed by the '--' to mark the end of the flags.

In version HMCCS1552002 the group's tranformation matrix follows; this is a 4 by 4 array of floating point numbers to specify the geometric tranformation to apply to objects inside the group. Use the identity matrix for no transformation.

In version HMCCS1552005, zero or more group transforms are specified using the #translate, #rotate, and #scale directives, which are described below. As usual, transforms are specified in the reverse order that they are applied.

The group shapes and subgroups are then specified. The end of the group is specified by a #group_end directive.

#translate dx dy dz

The translate directive specifies a translation by dx in the x direction, dy in the y direction, and dz in the z direction.

#rotate theta vx vy vz

The rotate directive specifies a rotate by theta degrees about the vector < vx,vy,vz &gg. This cannot be the zero vector!

#scale sx sy sz