Handles

Various resources are created during the definition of a scene, these resources are referenced in the Tcl code with handles. A handle is similar to a file id number returned by the open system call. It is an abstract entity that provides a reference to a resource that is internally managed. The following handles for the following resources are provided:

camera - A camera which specifies a point of view. The handle STDCAMERA is predefined camera located at (0.0, 0.0 10.0), looking at the origin, with the world y-axis as the up direction and a focal factor of 0.25.
light - A light source or spot light.
surface - Surfaces that are constructed from polygons that have been pushed on the polygon stack.
shader - A shader defines a shading algorithm and surface attributes required by the shader. This handle can be used to define the way surfaces will be shaded, including their color and attributes.
object - Objects defined in the SIPP internal database. A special handle WORLD is used to specify the world object.
pbmfile - A PBMPlus Portable Pixel Map (PPM) or Portable Bit Map (PBM) file.
rlefile - Utah Raster Toolkit RLE files.
pixmap - Memory resident pixel or bit map.

When a unreference operation is performed on a handle, a reference count is decremented, the resource is not actually deleted unless the reference count goes to zero. The handle itself is deleted. Thus an object is not released until its is handle is unreferenced and it is no longer a subobject of any object. This behavior applies to objects, surfaces, shaders and pixmaps.