tsipp

Section: User Commands (1)
Updated:
Index Return to Main Contents

NAME

tsipp - Tcl command interface to SIPP, the SImple Polygon Processor library.

INTRODUCTION

Tcl-SIPP provides a Tcl command interface to SIPP, the SImple Polygon Processor library. This provides a command interface for creating 3-dimensional scenes and rendering them using a scan-line z-buffer algorithm. The Tcl interpretive programming language is used to provide a powerful, yet simple interface to this library. The scene may be written to either a PPM format file, as defined by the PBMPLUS toolkit or a RLE file, as defined by the Utah Raster Toolkit.

INVOCATION

Tcl-SIPP follows the calling conventions of the Tcl shell provided with Extended Tcl. The command line is:

    tsipp [-q] [[-f] script]|[-c command] [args]

See the TclX manual page for details of the arguments and flags.

DATA TYPES AND RESOURCES

The following data structures are used by Tcl-SIPP:

o color - A list containing the red, green and blue values for the surface. Each being a number between 0.0 and 1.0.

o opacity - Describes the opacity of a surface. 0.0 means totally transparent, 1.0 means totally opaque. May be a list of red, green and blue opacity values or a single value to be used for all color channels.

o vertex - A vertex is defined by a Tcl list of 3 floating point numbers in the form: {x y z}.

o vertex/texture pair - A vertex and corresponding texture coordinates are defined by a Tcl list of two list, each having 3 floating point numbers in the form: {{x y z} {u v w}}.

o vector - A vector is defined by a Tcl list of 3 floating point numbers in the form: {x y z}.

o boolean - Boolean arguments may be specified as `0' or `1', `true' or `false', `t' or `f' (upper or lower case). Only `0' or `1' are valid in Tcl expressions and commands that return booleans only return `0' or `1'.

o angle - An angle may be expressed in degrees or radians. If the number is prefixed with an "R", then it is taken as radians, if it is prefixed with "D", then it is taken as radians. (e.g. 1.2, R1.2, D10.5). If no prefix is specified, some commands assume degrees, some assume radians. See the documentation of the specific command.

o matrix - A 4x4 transformation matrix is represented as a list of 4 elements, each element being a row. Each of the row elements is a list of 4 floating point numbers, representing the columns. The values in column 4 must be 0, 0, 0, 1. For example:

        {{1.2  1.4  0.1  0}
         {2.1  2.3  1.6  0}
         {2.4  6.1  2.6  0}
         {2.9  1.1  3.6  1}}

Be careful, many commands take lists of the above data types, which are themselves lists.

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:

: o 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. STDCAMERA is an alias for a pre-created camera camera0. All standard camera commands will work on this camera, including deleting it.
: o light - A light source or spot light.
: o surface - Surfaces that are constructed from polygons that have been pushed on the polygon stack.
: o 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.
: o object - Objects defined in the SIPP internal database. A special handle `WORLD' is used to specify the world object.
: o rlefile - Utah Raster Toolkit RLE files.

When a delete operation is performed on a handle, a use count is decremented, the resource is not actually release unless the use count goes to zero. Thus a handle to a object that has been added as a subobject of another object may be deleted with out release the subobject.

POLYGON AND SURFACE CREATION COMMANDS

These commands provide for the definitions of polygons and the creation of surfaces from the polygons. There is a vertex stack for defining polygons and a polygon stack for defining surfaces. The surfaces are referenced by surface handles.

SippVertexPush [-tex] vertexList: Push a list of vertices or vertex and texture coordinate pairs onto the internal vertex stack. There texture coordinates are currently not use in any Tcl/SIPP rendering commands. The vertices must be pushed on the vertex stack counterclockwise when looking at the "front" face of the polygon. Otherwise the front of the surface will be defined in the wrong direction. If -tex is specified, then the list contains both vertices and texture coordinates, each element being in the form "{x y z} {u v w}". If -tex is not specified, then the list contains just vertices, each element being in the form "{x y z}".
SippPolygonPush [[-tex] vertexList]: Create a polygon from the vertices on the vertex stack and push it onto the polygon stack. The vertex stack is empty and ready for a new polygon definition after this operation. Optional push a list of vertices or vertex and texture coordinate pairs onto the internal vertex stack before creating the polygon. See SippPolygonPush for details.
If a vertex in the polygon is already defined in a previous polygon that belongs to the same surface, the same vertex will be referenced, i.e. vertices shared between polygons are only stored once, but they must be repeated when defining the polygons.
SippSurfaceCreate shaderhandle: Create a surface from the polygons on the polygon stack. A handle to the newly-created surface is returned. The polygon stack is empty afterwards. shaderhandle is a handle to the shader, which specifies a shading algorithm and surface description. See the section SHADER COMMANDS.
SippSurfaceDelete surfacelist: Decrement the reference count on all surface handles in surfacelist. If the reference count goes to zero the surface will be released. In either case, the surface handle will be released.
SippSurfaceSetShader surfacelist shaderhandle: Set the all of the surfaces in the list surfacelist to be shaded with the the shader shaderhandle.

SHADER COMMANDS

These commands creates a surface shading description, which consists of a shading algorithm specification and surface attributes. They returns a shader handle that can be passed to other commands.

SippShaderBasic ambient specular c3 color [opacity]

Create a basic shader, which is a modified and simplified version of Blinn's shading model.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

color is a list containing the red, green and blue values for the surface. Each being a number between 0.0 and 1.0.

opacity describes the opacity of a surface. 0.0 means totally transparent, 1.0 means totally opaque. May be a list of red, green and blue opacity values or a single value to be used for all color channels. Optional, default is 1.0.

SippShaderPhong ambient diffuse specular spec_exp color [opacity]

Create a shader that implements the Phong illumination model.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

diffuse is a value between 0.0 and 1.0 specifying how much light that is reflected diffusely from the surface.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

spec_exp is the exponent in the specular highlight calculation. It specifies how "shiny" the surface is. Useful values are about 1 to 200, where 1 is a rather dull surface and 200 is a very shiny one.

color is a list containing the red, green and blue values for the surface. Each being a number between 0.0 and 1.0.

SippShaderStrauss ambient smoothness metalness color [opacity]

This is an implementation of a shader described by Paul Strauss in IEEE CG&A Nov. 1990. In his article he explains that most shading models in use today, ie Phong, Cook-Torrance, are difficult to use for non-experts, and this for several reasons. The parameters and their effect on a surface are non-intuitive and/or complicated. The shading model Strauss designed has parameters that is easy to grasp and have a reasonably deterministic effect on a surface, but yet produces very realistic results.

ambient is a value between 0 and 1 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

smoothness is a value between 0 and 1 that describes how smooth the surface is. This parameter controls both diffuse and specular reflections. 0 means a dull surface while 1 means a very smooth and shiny one.

metalness is also a value between 0 and 1. It describes how metallic the material is. It controls among other things how much of the surface color should be mixed into the specular reflections at different angles. 0 means a non-metal while 1 means a very metallic surface.

color is a list containing the red, green and blue values for the surface. Each being a number between 0.0 and 1.0.

SippShaderWood ambient specular c3 scale basecolor ringcolor [opacity]

This shader creates a simulated wood texture on a surface. It uses two colors, one as the base (often lighter) color of the wood and one as the color of the (often darker) rings in it. The rings is put into the base color about the x-axis and are then distorted using noise() and turbulence(). A similar pattern is repeated at regular intervals to create an illusion of logs or boards.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

scale is a factor which determines the size of the wood pattern depending on the size of the texture coordinate system in relation to the world coordinate system. You will have to experiment some to get this right.

basecolor is a list containing the red, green and blue values for the wood base. Each being a number between 0.0 and 1.0.

ringcolor is a list containing the red, green and blue values for the wood rings.

SippShaderMarble ambient specular c3 scale basecolor stripcolor [opacity]

This shader creates a simulated marble texture on a surface. It uses two colors, one as the base material and one as the interspersed material. The interspersed material is put into the base material in strips that are distorted using noise() and turbulence().

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

scale is a factor which determines the size of the marble pattern depending on the size of the texture coordinate system in relation to the world coordinate system.

basecolor is a list containing the red, green and blue values for the base material. Each being a number between 0.0 and 1.0.

stripcolor is a list containing the red, green and blue values for the interspersed material.

SippShaderGranite ambient specular c3 scale color1 color2 [opacity]

This shader is very similar to marble shader in that it also mixes two colors using noise() and turbulence(). The difference is in how the mixing is done. The two colors are mixed without treating them separately in any way.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

scale is a factor which determines the size of the granite pattern depending on the size of the texture coordinate system in relation to the world coordinate system.

color1 and color2 is a list containing the red, green and blue values for the base material. Each being a number between 0.0 and 1.0.

stripcolor is a list containing the red, green and blue values for the interspersed material.

SippShaderBozo colorlist ambient specular c3 scale [opacity]

This shader uses noise() to chose a color from a fixed set. The range of possible return value from noise() are divided into parts of equal size and each part is assigned a color. The size of the parts are dependent on the number of colors.

colorlist is a list contain one or more colors. Each color is a list containing the red, green and blue values for the surface. Each being a number between 0.0 and 1.0.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

scale is a factor which determines the size of the pattern depending on the size of the texture coordinate system in relation to the world coordinate system.

SippShaderBumpy shaderhandle scale [BUMPS] [HOLES]

This shader is a function that perturbates the normal of a surface using noise(). Any other shader can be used to do the final shading calculations.

shaderhandle is a handle to another shader and surface specification.

scale is a factor which determines the size of the granite pattern depending on the size of the texture coordinate system in relation to the world coordinate system.

BUMPS indicates that only bumps standing out from the surface are visible, the rest of the surface is smooth.

HOLES indicates that only bumps going into the surface are visible, the rest of the surface is smooth. If neither HOLES or BUMPS or specified, then both are assumed to be on.

SippShaderPlanet ambient specular c3 [opacity]

This shader is a somewhat specialized shader that produces a texture that resembles a planet surface. The planet is of the Tellus type with a mixture of oceans and continents. Some of the surface is covered by semi-transparent clouds which enhances the effect greatly. On the other hand, no polar caps are provided and this decreases the realism.
The texture is 3-dimensional, so it is possible to create cube planets or even planets with cut-out parts that still have surfaces that resemble the earth surface. The texture is not scalable, and is designed to be used with texture coordinates in the range -1.0 to 1.0, e.g. a unit sphere. Of course the world coordinates need not have the same order of magnitude.

ambient is a value between 0.0 and 1.0 which determines how much of the base color of a surface that is visible when it is not illuminated by any lightsource.

specular is a value between 0.0 and 1.0 which is the fraction of color specularly reflected.

c3 is the shininess of the surface where 0.0 is the most shiny and 1.0 is the most dull.

SippShaderDelete shaderlist

Delete the shader specifications in the list of shader hadles, shaderlist. This command only release the handles associated with the shaders, the shader and surface descriptions still remain associated with any surfaces that use them.

OBJECT MANIPULATION COMMANDS

These commands are provided for creating and manipulating objects. An object is referenced by an object handle.

SippObjectCreate: Create an empty object, i.e. an object with no surfaces or subobjects in it. The transformation matrix in the new object will be a identity matrix initially. A handle to the object is returned which is passed to the other object commands to specify this object. Object must be added as a sub-object of the `world' object or some other object to be become part of the scene.
SippObjectDelete objectlist: Delete the all objects whose handles are in the list objectlist. The memory used by the objects and all its subobjects and surfaces is recursively freed. sipp keeps track of internal references so objects and surfaces referenced from somewhere else in sipp will not be deleted.
SippObjectInstance objecthandle: Create a new instance of a previously defined object referenced by objecthandle. The lists of surfaces and subobjects in the object are not copied, but a new reference with its own transformation matrix is created. The matrix is set to the identity matrix. If the object is changed, i.e. if one of its subobjects or surfaces are transformed, one is deleted or added, the change will also be seen in the copy.
SippObjectDup objecthandle: Copy recursively an object and its subobjects. The surfaces in the object tree are not copied, only new references to them are made.
SippObjectDeepDup objecthandle: Copy the entire tree of an object, including subobjects and all surfaces, polygons and vertices. This is a costly operation if the object is complex.
SippObjectAddSurface objecthandle surfacelist: Add the surfaces in the list surfacelist to the specified object.
SippObjectSubSurface objecthandle surfacelist: Remove (subtract) the surfaces in the list surfacelist from the specified object.
SippObjectAddSubobj objecthandle subobjlist: Add the objects in the list subobjlist to the specified object.
SippObjectSubSubobj objecthandle subobjlist: Remove (subtract) the objects in the list subobjlist from the specified object.
SippObjectGetTransf objecthandle: Return the transformation matrix currently stored in the object specified object.
SippObjectSetTransf object matrix: Set the transformation matrix of the specified object to matrix.
SippObjectClearTransf object: Set the transformation matrix of the specified object to the unit matrix.
SippObjectTransform object matrix: Post multiply specified matrix into the transformation matrix of object.
SippObjectRotateX object angle: Rotate the object angle radians or degrees about the X axis. The angle is radians if no prefix or if the number is prefixed with an "R" and is degrees, prefixed with "D".
SippObjectRotateY object angle: Rotate the object angle radians or degrees about the Y axis. The angle is radians if no prefix or if the number is prefixed with an "R" and is degrees, prefixed with "D".
SippObjectRotateZ object angle: Rotate the object angle radians or degrees about the Z axis. The angle is radians if no prefix or if the number is prefixed with an "R" and is degrees, prefixed with "D".
SippObjectRotate objecthandle point vector angle: Rotate the specified object angle radians or degrees about the line given by point and vector starting in that point. The angle is radians if no prefix or if the number is prefixed with an "R" and is degrees, prefixed with "D".
SippObjectScale objecthandle factor|{xfactor yfactor zfactor}: Scale the specified object with the scaling factors xfactor,yfactor and zfactor in the main directions respectively. If only factor is specified, it is used as the scaling factors in all directions.
SippObjectMove objecthandle {xdist ydist zdist}: Move (translate) the specified xdist, ydist and zdist in the three main directions, respectively.

PRIMITIVE OBJECT CREATION COMMANDS

These commands create primitive objects of specific shapes.

Texture mappings algorithms are supported for primitive objects:

Each object primitive which can be created in SIPP has an argument that describes what kind of texture coordinates should be assigned to the surface of the object. This parameter can have one of the following predefined values:

o NATURAL - This value tell SIPP to use a two dimensional mapping which is "natural" for this particular object. It might be one of the other available mappings or it might be something unique for the object. The description of the functions for creating the individual objects specifies how this mapping is done.

o CYLINDRICAL - A two dimensional mapping. The coordinates are assigned as if the object were projected on a cylinder surrounding the object and centered on the z-axis object. The coordinates are mapped so that `x' goes from 0 to 1 around the base of the cylinder and `y' goes from 0 to 1 from bottom to top on it.

o SPHERICAL - Same as `CYLINDRICAL', but the object are projected on a sphere surrounding it instead.

o WORLD - A three dimensional mapping. The texture coordinates are the same three dimensional coordinates as the world coordinates of the object at creation time.

SippTorus bigradius smallradius radialres tuberes shaderhandle [texture]

Create a torus centered about the origin and with the z-axis pointing up through the ring. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. bigradius is the radius of the ring and smallradius is the radius of the "tube" itself. radialres is the number of polygons that will be created radially around the ring and tuberes is the number of polygons that will be created around the tube.
Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is a two dimensional mapping with the x coordinate going around the small circle and the y coordinate going around the large circle.
An object handle that references the new object is returned.

SippCone bottomradius topradius length resolution shaderhandle [texture]

Create a cone centered about the origin and with the z-axis along the cones main axis. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. bottomradius and topradius determines the radius of the cone in its bottom and top, if both of these are non zero a truncated cone is created. length defines the length of the cone. resolution is the number of polygons that will be created radially around the rim.
Texture is the texture mapping algorithm to use for the object. The NATURAL' texture mapping is CYLINDRICAL.
An object handle that references the new object is returned.

SippCylinder radius length resolution shaderhandle [texture]

Create a cylinder centered about the origin and with the z-axis along the cylinders main axis. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. radius and length defines the size of the cylinder. resolution is the number of polygons that will be created radially around the rim.

Texture is the texture mapping algorithm to use for the object. The NATURAL' texture mapping is CYLINDRICAL.

An object handle that references the new object is returned.

SippEllipsoid {xradius yradius zradius} resolution shaderhandle [texture]

Create a ellipsoid centered about the origin. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. xradius, yradius and zradius defines the size of the ellipsoid. resolution is the number of polygons that will be created around it's "equator".
Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is SPHERICAL.
An object handle that references the new object is returned.

SippSphere radius resolution shaderhandle [texture]

Create a sphere centered about the origin. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. radius defines the size of the sphere. resolution is the number of polygons that will be created around it's "equator".

Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is SPHERICAL.

An object handle that references the new object is returned.

SippPrism 2dpointlist length shaderhandle [texture]

Creates a prism defined by the polygon in 2dpointlist. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. 2dpointlist is a list of lists of x and y pairs. The prism will ascend and descend equally far (length / 2.0) from the x-y plane along the z axis.

Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is similar to CYLINDRICAL but the x coordinate is not taken from projection on a cylinder but is evenly distributed around the perimeter. An odd thing in all the 2D mappings (all except WORLD) for the prism is that the top face will have texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).

An object handle that references the new object is returned.

SippBlock {xsize ysize zsize} shaderhandle [texture]

Creates a square block with the size defined by xsize, zsize and zsize. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. The block is centered about the origin.
Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is similar to CYLINDRICAL but the x coordinate is not taken from projection on a cylinder but is evenly distributed around the perimeter. An odd thing in all the 2D mappings (all except WORLD) for the block is that the top face will have texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).
An object handle that references the new object is returned.

SippCube size shaderhandle [texture]

Create a cube with the side of length side. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. The cube is centered about the origin. surface is the surface description used by shader() which is the shading function used when shading the cube.
Texture is the texture mapping algorithm to use for the object. The NATURAL texture mapping is similar to CYLINDRICAL but the `x' coordinate is not taken from projection on a cylinder but is evenly distributed around the perimeter. An odd thing in all the 2D mappings (all except WORLD) for the cube is that the top face will have texture coordinates (0.0, 1.0) while the bottom will get (0.0, 0.0).
An object handle that references the new object is returned.

SippBezierCurve resolution vertexlist curvelist shaderhandle [texture]
Define an object using a Bezier curve rotated about the z-axis. Resolution it the number of polygons to tessellate the surface into. Vertexlist is a list of vertices of the curve. Each element of the list is a list contain the X, Y and Z vertices.
Curvelist a list of indices into vertexlist that defined the curve. Each element of the list contains a list of 4 indices. These indices are zero based. For example:

{{0 1 2 3} {4 4 5 7} {6 7 8 9}}

shaderhandleis handle to a previously created surface shading specification.
Texture is the texture mapping algorithm to use for the object. The texture coordinates are a bit special for these surfaces. SPHERICAL and CYLINDRICAL mappings are not applicable, and NATURAL mapping will apply to the piece of surface created by each Bezier curve separately. The NATURAL mapping uses the curve parameter u along each curve as x coordinate and goes from 0 to 1 around the perimeter of the rotational surface on the other axis
An object handle is returned.

SippBezierPatch resolution vertexlist patchlist shaderhandle [texture]
Define an object using a Bezier patch. resolution is the number of polygons to tessellate the surface into. Vertexlist isA list of vertices of the curve. Each element of the list is a list contain the X, Y and Z vertices.
Patchlist is list of indices into vertexlist that defined the patch. Each element of the list contains a list 4 lists. Each of these lists contain 4 indices. The indices are zero based. For example:

{{ 0 1 2 3} {35 36 37 38} {28 29 30 31} {21 22 23 24}} {{21 22 23 24} {14 15 16 17} { 7 8 9 10} { 0 1 2 3}} {{ 3 4 5 6} {38 39 40 41} {31 32 33 34} {24 25 26 27}} {{ 6 5 4 3} {13 12 11 10} {20 19 18 17} {27 26 25 24}}}

Shaderhandle is handle to a previously created surface shading specification.
Texture is the texture mapping algorithm to use for the object. The texture coordinates are a bit special for the Bezier patches. CYLINDRICAL and SPHERICAL coordinates are not applicable, if they are specified, SIPP will use NATURAL anyway. The NATURAL mapping is a two dimensional mapping using the surface parameters u and v, see figure below. Note that these parameters range from 0 to 1 within each patch!
An object handle is returned.

SippBezierFile fileid resolution shaderhandle [texture]

Read a file specified by fileid, containing descriptions of a set of Bezier patches or Bezier curves. The surface is shaded with the algorithm and surface parameters specified by shaderhandle. See the sipp primitives manual page for a description of this file format. The SippBezierCurve and SippBezierPatch commands are the preferred method of creating Bezier surfaces, this command is provided for compatibility with existing SIPP data files.

If the file contains descriptions of patches, these patches will be tesselated into resolution by resolution polygons and installed in a sipp object as one surface.

If the file contains descriptions of curves, a rotational surface will be created by rotating these curves about the y-axis. The resulting surface will be tesselated into polygons and installed in a sipp object as one surface.

Texture is the texture mapping algorithm to use for the object. The texture coordinates are a bit special for the Bezier patches. CYLINDRICAL and SPHERICAL coordinates are not applicable, if they are specified, SIPP will use NATURAL anyway. The NATURAL mapping is a two dimensional mapping using the surface parameters u and v, see figure below. Note that these parameters range from 0 to 1 within each patch!

An object handle that references the new object is returned.

LIGHT SOURCE AND VIEWING COMMANDS

These commands specify the light sources and the viewing parameters.

SippLightSourceCreate {x y z} color type

Create a new lightsource in the scene. If a directional lightsource is created these {x y } specifies a vector in the direction that the light emanates the lightsource. If it is a point lightsource they specify the exact location of it. Color specifies the color and intensity of the light. Type is either `DIRECTION' or `POINT'. A light handle is returned by the command.

SippSpotLightCreate position point opening color type shadow

Create a new spotlight in the scene. Position is the coordinates of the spotlight. Point is a point at which the spotlight is pointing. It is in the middle of the lightcone. Opening is the opening angle of the lightcone. The cone defined will be completely lit, a soft edged lightcone will start to blend out outside this angle. If the number is prefixed with an "R", then it is taken as radians, if it is prefixed with "D", then it is taken as radians. If not prefix, then degrees is assumed. Color is The color of the emitted light. Type is the type of spotlight to create. Should be either "SHARP" or "SOFT". Shadow is a boolean that indicates if light from the spotlight will be able to cast shadows. Whether shadows actually are cast or not depend on which value set by the SippShadows command. A light handle is returned by the command.

SippLightDestruct lightlist

Delete lightsources or spotlights. Lightlist is a list of light handles to destruct.

SippLightSourcePut light {x y z}

This command is used to modify the direction, or position, of a lightsource. If the light is a directional light, then x, y, z are a vector in the direction that the light emanates. If the light is a point light source, then x, y, z are the coordinates of the new location of a light.

SippSpotLightPos light {x y z}

Modify the position of a spotlight. X, y, z are the coordinates of the new location of a light.

SippSpotLightAt light {x y z}

Modify the position a spotlight is pointing at. X, y, z are the coordinates of the point that the light should point at.

SippSpotLightOpening light opening

Modify the opening angle of the lightcone of a spotlight. Opening is the opening angle of the lightcone. The cone defined will be completely lit, a soft edged lightcone will start to blend out outside this angle. If the number is prefixed with an "R", then it is taken as radians, if it is prefixed with "D", then it is taken as radians. If not prefix, then degrees is assumed.

SippSpotLightShadows light flag

Turn shadow casting on or off for a specific spotlight. Shadow is a boolean that indicates if light from the spotlight will be able to cast shadows.

SippLightColor light color

Change the color of the emitted light from a lightsource or a spotlight. fIColor is the new color of the light.

SippLightActive light flag

Turn a lightsource or a spotlight on or off. Flag is boolean indicating if a light should be active.

SippCameraCreate [position] [point] [upvector] [focal]

Create a new camera. Positon is the point to world coordinates of the camera. Point is a world corrdinates point that he camera is to look at. Upvector is a vector defining the up direction. The only constraint on this vector is that it must not be parallel to the viewing direction.

Focal the focal ratio of the "camera". This is the ratio between the distance from the viewpoint to the screen and half the screen height. A large focal factor will result in a wide angle view while a small factor will give a telescopic effect.

                                screen
                                |
                                | s
    viewpoint                   |
        *-----------------------|
                    d           |
                                |
                                |

        focal = s / d

If any of the parameters is omitted or has a empty value, then that parameter is defaulted. A camera handle is returned. If a camera is not created, the default camera, STDCAMERA, is used.

SippCameraDestruct cameralist

Delete one or more cameras. Cameralist is a list of camera handles,

SippCameraParams camera [position] [point] [upvector] [focal]

Alter the parameters of a camera. Camera is the camera handle, all other arguments are the same as for SippCameraCreate. If any of the parameters is omitted or has a empty value, then that parameter is unchanged.

SippCameraUse camera

Specify the camera to use as the current viewpoint.

PORTABLE BITMAP RENDERING COMMANDS

These commands are used for rendering to files defined by the PBMPLUS toolkit, either PPM files for fully rendered images or PBM files for line images.

SippPPMRender [-flag] fileid xsize ysize [mode]: [oversample]
This command does the rendering of a scene. The image is created with the pixel dimensions xsize by ysize. Fileid is an id of a open file, as returned by the open command. The image is written in the Portable Pixel Map (PPM) format unless mode is LINE, in which case it is written in the Portable Bit Map (PBM) format. fIMode decides in which mode the image should be rendered and should be one of PHONG, GOURAUD, FLAT or LINE. The integer value oversampling controls how much oversampling should be done for anti-aliasing. Each pixel will be the average of a oversampling X oversampling matrix of subpixels. Oversampling is ignored if mode is LINE.
The optional flag -flag is used to do interlaced rendering, which is useful for animations. If -ODD is specified, the odd scanlines are rendered, if -EVEN is specified, then even scanlines are rendered. If -BOTH is specified or the flag is omitted, then all scanlines are rendered. Interlaced rendering is not allowed if mode is LINE.

RLE FILE MANIPULATION AND RENDERING COMMANDS

These commands are used to open, manipulate and render to RLE files as defined by the Utah Raster Toolkit.

SippRLEOpen filename mode

Open the RLE file filename. Mode is "w" to create or truncate the file and "a" to create or open for appending. The append option allows for creating RLE files containing several images. The command returns a handle to the RLE file. Filename follows the full semantics of the file name argument to the Tcl open command. Thus the RLE file may be sent to a pipeline, which could be a viewer or post-processing program. Thus to render an image directly into the RLE X11 file view:

    set image [SippRLEOpen "|getx11" "w"]

SippRLEClose rlehandle

Close the RLE file specified by rlehandle.

SippRLEPutCom rlehandle name [value]

Set a comment in the RLE file specified by rlehandle. A RLE comment is similar to an environment variable. This sets a comment of name name to the string value. If value is omitted, then the name is saved, without a value.

SippRLEGetCom rlehandle name [retvar | {}]

Return the value of comment identified by name from a RLE file specified by rlehandle. If retvar is specified the command returns `1' if the comment is found and `0' if it is not found. The value of the comment is returned in the variable retvar, unless retvar is `{}', in which the only the presence of the variable is returned, but not value. If retvar is not specified, the command returns the value of the comment or an empty string if the comment has no value or is not found.

SippRLEDelCom rlehandle name

Delete the comment name from the RLE file specified by rlehandle.

SippRLERender [-flag] rlehandle xsize ysize [mode]

[oversample]
This command does the rendering of a scene. The image is created with the pixel dimensions xsize by ysize. It is written the RLE file specified by rlehandle. Mode decides in which mode the image should be rendered and should be one of PHONG, GOURAUD, FLAT, or LINE. The integer value oversampling controls how much oversampling should be done for anti-aliasing. Each pixel will be the average of a oversampling X oversampling matrix of subpixels. Oversampling is ignored for LINE mode.

The optional flag -flag is used to do interlaced rendering, which is useful for animations. If -ODD is specified, the odd scanlines are rendered, if -EVEN is specified, then even scanlines are rendered. If -BOTH is specified or the flag is omitted, then all scanlines are rendered. Interlaced rendering is not allowed if mode is LINE.

MISCELLANEOUS COMMANDS

A few more useful commands.

SippShowBackFaces [flago]: This function can be used if backface culling should not be performed. If the boolean flag is true backfacing polygons are "inverted" (their surface normal is negated) and then rendered. This is useful if an object description does not use a consequent ordering of the vertices. This also controls hidden line elimination when doing line rendering. The rendering step can be slowed down considerably since, on the average, twice as many polygons need to be rendered. The default is that backface culling should be performed (false). If flag is not specified, the current value is returned.
SippBackground [color]: Set the background color of the image to color. If color is not specified, the the current background color is returned.
SippLineColor [color]: Set the color of lines to use in line mode rendering to color. This is only useful when rendering to RLE files, it is ignored for PBM files. If color is not specified, the the current line color is returned.
SippShowShadows flag [size]: This command globaly enables or disables the casting of shadows by objects. If the boolean flag is true, then shodows will be cast by lights that have shadows casting enabled. Size defines the size of the depth map used to render the shadows. As a rule of thumb one could say that the depth maps should be at least as large as the image itself but this may vary from case to case. Size is omitted when flag is false.
SippInfo attribute: This command returns various pieces of information about Tcl-Sipp. The following values may be specified for attribute:
: o version - Returns the full Tcl-SIPP version. This includes the SIPP library version number, a suffix indicating the Tcl-SIPP interface version and the Tcl-SIPP interface patch level (if its been patched).
: o sippversion - Returns the SIPP library version number that Tcl-SIPP is linked with.
: o tsippversion - Returns the Tcl-SIPP interface version (the suffix in the full version).
: o tsipppatchlevel - Returns the Tcl-SIPP interface patchlevel.
: o rle - Returns 1 if Tcl-SIPP is linked with the RLE libraries and can product RLE files. Returns 0 if RLE file support is not available.
SippMkVector {pt0_x pt0_y pt0_z} {pt1_x pt1_y pt1_z}: Create a vector in the director going from the point defined by pt0_x, pt0_y, pt0_z to the point defined bypt1_x, pt1_y, pt1_z.
SippMatMult matrix1 matrix2: Multipy matrix1 by matrix2.

NOTES

o Extended Tcl handles signals that are trapped by setting a flag indicating that a particular signal occured and then processing it when the current Tcl command has completed. The Tcl-SIPP rendering commands may take a very long time. Extended Tcl catches SIGINT by default. If you wish to be able to always abort your scripts with SIGINT, issue the following command from your script:

        signal default SIGINT

o Although the Tcl interface tries to validate argument data, SIPP itself is not very bullet proof. Incorrect or out of range data can cause unfriendly failures, including core dumps. If you have problems, check the values being passed to a command.

o Memory associated with shaders is never released, as SIPP does not keep a use count on the Surf_desc data structure once associated with a surface. However, the memory associated with shaders is small.

o No command is implement using the mask shader.

o While texture coordinates may be specified for a surface, there is currently no way to use them.

o The Bezier File command returns errors to stderr rather than via the Tcl error mechanism.

AUTHOR OF THE TCL INTERFACE

Mark Diekhans (markd@grizzly.com). Please e-mail questions, comments and suggestions.

Index

NAME
INTRODUCTION
INVOCATION
DATA TYPES AND RESOURCES
POLYGON AND SURFACE CREATION COMMANDS
SHADER COMMANDS
OBJECT MANIPULATION COMMANDS
PRIMITIVE OBJECT CREATION COMMANDS
LIGHT SOURCE AND VIEWING COMMANDS
PORTABLE BITMAP RENDERING COMMANDS
RLE FILE MANIPULATION AND RENDERING COMMANDS
MISCELLANEOUS COMMANDS
NOTES
AUTHOR OF THE TCL INTERFACE

This document was created by man2html, using the manual pages.
Time: 00:17:51 GMT, December 05, 2024