SL Documentation

 
Contents
Introduction

This document is a little unfinished. Kick me.
 
Objects

object "name"  ...  end

Create an object. An object consists of an ordered list of attributes and primitives, followed by the "end" keyword. Attributes define
properties, and primitives define things to be drawn using those properties. An object is itself a primitive, and thus often includes other objects, creating an object hierarchy.

All attribute settings within an object definition affect the following attributes or primitives in that object.

objectfile "filename" [options]
Include a scene file from elsewhere. The file can be in any of the supported formats -- it is quite possible to include a wavefront "obj" file in an sl scene, for instance.

Possible options:
-unit            rescale model so it fits in a 2x2 cube lying on the x-y plane.
-zup            the model is defined with the z axis being up: rotate accordingly


 
Attributes

colour [r g b]

Set current colour (reflectance).
emittance [r g b]
Set current emittance.
camera [options]
Define a camera. Possible options:

-zup

points [[x0 y0 z0] [x1 y1 z1] ...]
Define the current points array
indexes [i0 i1 i2 ...]
Define the current indexes array: a list of indexes into the points array


scale [sx sy sz]

Create the matrix that scales about the origin by sx along the x axis, sy along the y axis, sz along the z axis, and concatenate onto the matrix stack.
scalef s
Do the same for a uniform scaling by s.
rotate [x y z] theta
Do the same for the matrix that rotates around the axis [x y z] by theta. theta is in degrees.
shift [tx ty tz]
Do the same for the matrix that translates by the vector [tx ty tz]
avar name avar_type [min_value default_value max_value] [av_x av_y av_z]
This defines an avar, which is a transform that can be adjusted externally. The avar_type can be colour, emittance, shift, rotate, or scale. e.g.,
avar light_shift shift [0 1 10] [1 0 0]
    # a shift in the x direction, between 0 and 10 units, default 1 unit.
    avar floor_colour colour [0 1 1] [0 0 1]
    # varies the current reflectance between black and pure blue.
 
 
Primitives

poly

Draw the polygon defined by the current indices or points.
tetrahedron
cylinder
cone
cube
sphere
square
Draw the (unit-sized) object in question. The cone and the tetrahedron have their bases resting on the x-z plane. All the other objects are centred on the origin.
Definitions

define "name"  ...  end

Define a primitive with the given name. This primitive can then be referenced in later object definitions by name, the same
as the built-in primitives listed above.
Notes

All attribute definitions set that attribute for the rest of the current object. They can be overridden by later definitions, e.g.,
    colour [1 0 0]
    ...
    colour [0 0 1]
    ...
    poly
would draw a green polygon. The exception to this is transformations, which accumulate. E.g.,
    rotate [1 0 0] 30
    scale [2 2 2]
    ...
    poly
will scale the polygon by a factor of 2, and then rotate it around the x axis by thirty degrees before displaying. The best trick for getting the hang of how tranformations apply to a particular primitive is to read backwards in the file, as transformations occur in the reverse order to which they are applied.
 
 
Examples

object "my_scene"

    object "light"
        emittance [1 0 0]
            # radiosity of light is red
        colour [1 0 0]
            # reflectance of light is 0, i.e. black
        points [[-1 1 -1] [1 1 -1] [1 1 1] [-1 1 1]]
            # define an array of points
        poly
            # draw the polygon defined by all those points
    end

    object "floor"
        colour [0.5 0.5 0.5]
            # floor is grey
        points [[-1 -1 -1] [-1 -1 1] [1 -1 1] [1 -1 -1]]
            # define an array of points
        indexes [0 1 2]
        poly
            # draw a triangle corresponding to points 0, 1 and 2
        indexes [2 3 0]
        poly
            # draw a triangle corresponding to points 2, 3 and 0
    end
end

The definition of the two triangles forming the floor could be replaced with:

        indexes [0 1 2 2 3 0]
        faces [0 3 6]
        mesh
            # draw the two polygons defined by indices 0..2 and 3..5

or even
        indexes [0 1 2 2 3 0]
        tri_mesh
            # draw triangles defined by 3i..3i + 2 for all possible i.