Each word written in lowercase in command syntax is a literal (keyword) that as to be reproduced verbatim. Uppercase words are argument names, these need to be substituted with the corresponding argument value when building the command.
Optional arguments are specified in brackets, e.g. [NX NY NZ]. Some commands require literal brackets, this is indicated by having space on both sides of the bracket, e.g. gtri VERT1 [ COLOR1 ] VERT2 [ COLOR2 ] VERT3 [ COLOR3 ].
When there are two or more discrete options, they are listed with | separating them, e.g. keepalive on|off.
Coordinates are unitless rational numbers along 3 axes (x, y and z). Coordinates are written in decimal format accepted by atof(3).
Vertices are specified in the vertex array of the object. A vertex reference is an integer that addresses an element of the object vert array. The first vertex is at index 0.
The Syntax is colon integer, e.g. :5 is the 6th vertex in the array.
Specifies a color in one of the following formats:
A matrix has 16 values, shown here in row-major order:
IX IY IZ _ JX JY JZ _ KX KY KZ _ SX SY SZ _These matrices specify object transformations and coordinate systems using three basis vectors I J K and a shift vector S. An input vector VX xy Vz is mapped as Vx * I + Vy * J + Vz * K + S. The values shown with an underscore are not used for the transformation, but can still make a difference with matrix multiplication.
Matrices can be specified as matrix expressions, which consist of one or more matrices multiplied (which works as if transformations were applied one after another - note that this is not a commutative operation!). Two matrices can be multiplied using the * operator.
A matrix can be specified using one of the following formats:
Typical examples:
obj "foo" mat rotx 45 * roty 90 * shift 10 7 11 - change the rotation and move the previously created object foo
cube scale 4 * shift 1 0 0 - create an 1x1x1 cube, scale it up to 4x4x4 and move it 1 unit on the X axis
Order of operations obviosuly does matter: a matrix expression starts with the identity matrix as the working matrix and executes each multiplication in order. At the end the final working matrix is used as the value of the expression.
When adding templates to objects, new templates are normally created with surface triangles facing outwards (normal vector pointing outwards). Triangles are one-sided, which means that if viewed from the inside, these objects would be invisible. This can be modified by specifying one of the following optional modifiers:
Note: anything else than "double" is a rendering optimization and makes any difference only if object culling is not turned off.
When a textual name or string has to be specified, one of two formats can be used:
Brigthness of surface fragments are calculated a formula similar t the oversimplified one:
output_brighthess = clamp(diffuse * light_angle + object_ambient)
Begin describing an object with the specified NAME. Object commands are documented in the object commands section. Object description lasts until the next global command. Entering an object definition doesn't "empty" the object - existing primitives aren't deleted (so new primitives will be appended). To redefine an object, use the empty or realempty command.
Move camera to specified eye position, looking at specified center point. The up vector is a vector pointing upwards from the camera (specifying camera orientation). The up vector can be omitted; in this case, projector tries to calculate a reasonable up vector, so that the plane defined by the (eye-center) vector and the up vector contains the Z axis, and the up vector points towards positive Z.
Place light source at coordinates X;Y;Z.
Sets diffuse intensity of the light. Acts as a multiplier to the material diffuse reflection factor. Default 1.
Set field of view (in degrees). Default 90.
Object with distance greater than NUM from the camera are not rendered. Useful on large landscape scenes to omit wasting CPU cycles on objects so far that they would be behind something else or would be a sub-pixel anyway. Default value is 1024.
Render frame.
Render frame then stop reading the input for DLY seconds timed from the last renderdelay (thus time spent on rendering is not added and a stable frame rate can be achieved). DLY is a positive rational number. Reports RENDERDELAY on STDOUT if events are enabled.
Stop reading the input for DLY seconds. DLY is a positive rational number. Unlike renderdelay, sleep does not try to time precisely and does not have any side effect.
Set background color to CLR (see colorspec).
Sets default ambient lighting factor. Default 1.
Sets default diffuse lighting factor. Default 0.
When on, do not exit upon EOF on STDIN.
When on, print events to STDOUT.
When on, hides the mouse cursor and grabs mouse input (mouse can not leave window).
When on, renders fog so distant objects gradually phase out instead of suddenly disappearing (see also: visibility). Supported only in opengl rendering (-g), software rendering ignores this.
Sets sensitive plane using 3 points. Sensitive plane is used to report a second set of coordinates (after screen coords) mapped onto this plane for mouse events. It is useful to get mouse coords in an absolute coordinate system within the 3d scene regardless of camera location and orientation. The coordinates are applied in the global coordinate system (not under any particular object).
Similar to gsense, but specifies the plane in the current coordinate system of the current object (relative to object position and transformations).
Load a texture from file at PATH and store it in memory as NAME. Name is an unique identifier of the texture. Both PATH and NAME are strings. File format of the texture is anything libsdl-image can load; typically png or jpeg. A texture file must contain exactly 256*256 pixels.
Specify the name of the texture used for all objects that are otherwise not textured locally. This option takes effect in rendering, not in object creation! If off is used instead of a texture name, non-textured objects remain non-textured in rendering.
Print STRING to STDOUT.
Points for primitives can be described in two ways: X Y Z - three numbers; add new vertex to object, use that vertex :N - use existing vertex reference
Show object (default).
Hide object.
Delete all primitives but not vertices or normals.
Delete all primitives, vertices and normals.
Set object position.
Set transformation matrix of current object. MEXPR is a matrix expression.
Set transformation matrix of current object. The shift/translation vector of the input matrix is ignored, only the basis vectors are applied. MEXPR is a matrix expression.
Set default color for primitives. Default black, but this isn't reset with entering new object definitions, so it has a global effect. CLR is a colorspec.
Specifies object texture and mapping mode. MODE is one of:
Removes local texture from object. Note: default (global) texture may still appply to the object at rendering.
Add a new primitive with the current color, that draws a line of multiple connected segments.
Append new vertices to the object vertex array.
Specify a triangle using 3 POINTs. Optional NX NY NZ specify surface normal vector; when not specified, it is calculated automatically. (Manually specified normal vectors can be used for bump maps.)
Same as tri but creates a quad.
Triangle colored in gradient with a target color specified for each vertex. COLOR1, COLOR2, COLOR3 are colorspec, POINT1, POINT2, POINT3 are the same as in tri.
Same as gtri, but creates a gquad.
Textured triangle. POINT1, POINT2, POINT3 are the same as in tri. The U and V numbers specify the texture coordinates for the three vertices (mapping a range of 0 to 1 on the texture image).
Same as ttri but creates a tquad.
Sets specular value on opengl material. Supported only in opengl rendering (-g), software rendering ignores this.
Sets shiny value on opengl material. Supported only in opengl rendering (-g), software rendering ignores this.
Set diffuse reflection factor of the object material (from 0 to 1).
Set ambient lighting value of the object material (from 0 to 1).
Render other object by name (usually useful when other object is hidden). Transformation matrix is local * other (the matrices of the local and the referenced objects are multiplied).
Render other object by name. Transformation matrix is local only (the transformation matrix of the referenced object is ignored).
Render other object name. Transformation matrix is other only (the transformation matrix of the referenced object is used; the local matrix is ignored).
Render other object by name. Transformation matrix is MEXPR * other * local. Can be used to copy the same object in different positions. MEXPR is a matrix expression.
Use material attributes of other object (color, texture, diffuse, ambient). Basically like "copy" & friends, but only for material attributes.
If camera distance exceeds CAMDIST, does a call NAME then stops processing this object. Can be used to have multiple versions of an object with different levels of detail.
If camera distance exceeds CAMDIST, does a copy NAME then stops processing this object. Can be used to have multiple versions of an object with different levels of detail.
Makes the current object static. The object is no longer allowed to be modified (can't add primitives or set transformation matrix). In return, the object can participate in frustum culling. Note that static objects can't reference (copy, call, etc.) non-static objects.
Generates vertex normals for all vertices in this object (as sums of the normals of the triangles that reference each vertex). Afterwards the triangles will be rendered using gouraud shading (with normal vector interpolation) instead of flat shading (using the same normal vector for the entire triangle).
Note: this command is not used for calculating simple surface normals of primitives like triangles or quads - that is done automatically if normals are not specified in the drawing command.
Create a named hot point in 3d space. NAME is an arbitrary string of at most 8 characters that identifies the hot point. When hot points are declared in a scene, mouse events report the name of the closest hot point as last argument of the event.
Turn off back-face culling of the current object. Normally objects are culled, which means each surface triangle is drawn only when its normal vector is facing the camera. When the normal vector is facing away, the triangle is not drawn. This is an optimization, which usually saves drawing half the triangles of somewhat symmetric objects.
See also: Common template modifiers when using template primitives.
Culling is turned on by default and is controlled on a per object basis.
Enable UV-mapping for this object. Instead of manually specifying U, V texture coordinates using TTRI, TQUAD commands, the specified matrix is used to transform object coordinates into UV (the resulting x and y are used for UV, z is ignored). Afterwards, normal trianges and quads become textured triangles and quads. Can be used to make object templates (like cube, cone, etc.) with textures. MEXPR is a matrix expression.
Add a transformed cube to current object. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed cone to current object. VERTNUM specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed hat to current object. A hat is a cone without bottom disc. VERTNUM specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed cylinder to current object. TOPDIA is the diameter of the top circle (1 if not specified). Bottom circle diameter is always 1. VERTNUM specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed tube to current object. A tube is a cylinder without top and bottom discs. TOPDIA is the diameter of the top circle (1 if not specified). Bottom circle diameter is always 1. VERTNUM specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed disc to current object. VERTNUM specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed wedge to current object. VERTNUM1 specifies the number of vertices along the base circle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed sphere to current object. VERTNUM1 and VERTNUM2 specify the number of vertices along the meridian and equator. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed hemisphere (a sphere cut in half with a horizontal plane along its equator) to current object. VERTNUM1 and VERTNUM2 specify the number of vertices along the meridian and equator. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed dome (a sphere cut in half with a horizontal plane along its equator) to current object. A dome is a hemisphere without bottom discs. VERTNUM1 and VERTNUM2 specify the number of vertices along the meridian and equator. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Add a transformed torus to current object. VERTNUM1 and VERTNUM2 specify the number of vertices along the meridian and equator of the bounding sphere. THICK is the dimater of the "tube" of the torus, between 0 and 1, relative to the overall diameter of the torus; a value close to 0 mean thin, a value close to 1 means the inner circle of the tube touch and there's no hole left in the middle. The transformation is done using the matrix expressionMEXPR. Invert and double are the common template modifiers.
Events are reported to STDOUT when enabled. Each report is a single line of text starting with the event name, written all uppercase. Event arguments are:
List of events printed by projector:
| event name | arguments | printed when |
|---|---|---|
| PRESS | BTN X Y SX SY SZ HOT | mouse button pressed |
| RELEASE | BTN X Y SX SY SZ HOT | mouse button released |
| MOTION | BTN X Y SX SY SZ HOT | mouse cursor moved (when not grabbed) |
| RMOTION | BTN RX RY | mouse cursor moved (when grabbed) |
| RESIZE | WIDTH HEIGHT | window resized to WIDTH * HEIGHT pixels |
| KEYDOWN | KMOD KUNI KNAME | keyboard key is pressed |
| KEYUP | KMOD KNAME | keyboard key is released |
| RENDERDELAY | DT RNDT | renderdelay has finished rendering and sleeping, input is read again |