SL Documentation


This document is a little unfinished. Kick me.

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


colour [r g b]

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


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.


Draw the polygon defined by the current indices or points.
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.

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.

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]
would draw a green polygon. The exception to this is transformations, which accumulate. E.g.,
    rotate [1 0 0] 30
    scale [2 2 2]
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.

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
            # draw the polygon defined by all those points

    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]
            # draw a triangle corresponding to points 0, 1 and 2
        indexes [2 3 0]
            # draw a triangle corresponding to points 2, 3 and 0

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

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

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