State information concerning the graphics device is held in an entity called the display context. Most transformation, clipping, and painting commands alter this state. Most drawing commands both use this state and alter it.
One of the more important components of the state is the current definition of the coordinate system. Points in the graphics display are refered to by pairs of real numbers. JaM maintains a transformation matrix for converting these numbers to the coordinates used by the display divice. The translation matrix affects only the placement of new objects on the display. Changing the transformation matrix with a transformation command affects the placement of already existing objects.
The state information also contains the position of a special point called the current draw position. The line drawing commands use the draw position to define one endpoint of the line. The draw position is also used to control the placement of text within the display.
There are several concepts common to many graphics commands. First of all, parametric cubic splines are used to specify curves. Cubic splines in turn are specified either in terms of the x and y coordinates of points, or by the coefficients of the actual parametric equations. Usually, the coordinates come from the mouse. A cubic spline segment may be specified by four points called its B ezier points. They have a specific mathematical relationship to the spline; informally, the spline passes through the first and fourth point, goes near the other two, and is always contained within the convex quadrilateral defined by the four points.
Many commands facilitate the building of paths made up of curves and straight lines. The path does not actually show up on the screen until a command is given to fill in the area enclosed by the path. There are commands which control how the area is filed in. In particular, some commands set up a clipping box which is intersected with the region to be filled in. There is also a painting function which controls the texture (halftone, etc.) of the shaded region.
.initdc b õ Initializes the stack of display contents.
.pushdc b õ Pushes a copy of the current display context onto the display contents stack.
.popdc b õ Replaces the current display context with that on top of the display context stack.
.translate <x><y> b õ The origin of the new coordinate system is set to the location of (x,y) in the old system.
.scale <sx><sy> b õ The coordinate system is expanded by sx in the x direction and sy in the y direction. The entire display is enlarged and lines are thickened. (Lines are normally about one unit wide).
.rotate <q> b see comment õ The coordinate system is rotated clockwise by q degrees.
.sixpoint <x0><y0><x1><y1><x2><y2><x3><y3><x4><y4><x5><y5> b õ Transform the coordinate system so that the first three points are mapped into the the last three.
.concat b õ Postmultiply the current transformation matrix by another transformation matrix.
.drawto <x><y> b õ Draw a line from the current draw position to the point (x,y). This moves the draw position too.
.rdrawto <x><y> b õ A line is drawn from the current draw position to the sum of that position and the vector (x,y). This moves the draw position as well.
.moveto <x><y> b õ The current draw position becomes the point (x,y).
.getpos b <x><y> õ Put the current draw position on the stack.
.rmoveto <x><y> b õ The vector (x,y) is added to the current draw position.
.drawboxarea <llx><lly><urx><ury> b õ A filled box is drawn with the given lower left corner and upper right corner. The draw position is left at the lower left corner.
.drawcubic <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b õ A cubic is drawn with the given coeficients in its parametric equation.
.beziertocubic <x0><y0><x1><y1><x2><y2><x3><y3> b <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> õ Four B ezier control points are converted to the parametric form of a cubic.
.cubictobezier <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b <x0><y0><x1><y1><x2><y2><x3><y3> õ The parametric form of a cubic is converted to its four B ezier control points.
.startpath b õ A path is started for the area generation machinery. Subsequent .enter, etc. commands will add to the path. The interior of the path is determined by a winding number technique.
.starteopath b õ A path is started for the area generation machinery except that even/odd parity is used to determine interior. There is a difference only in paths which cross themselves.
.enterpoint <x><y> b õ This command which must be preceded by .startpath, enters the point (x,y) in the current path. Successive .enterpoint's create polygonal paths.
path <i> b õ Enter a path defined by i calls to the .touch function. This is equivalent to i repititions of: .touch .enterpoint''.
.enterrect <llx><lly><urx><ury> b õ The rectangle defined by the given lower left and upper right corners is entered into the current path.
rect rect b õ The rectangle defined by to calls to the .touch function (see below) is entered into the current path.
.entercubic <C0(x)><C0(y)><C1(x)><C1(y)><C2(x)><C2(y)><C3(x)><C3(y)> b õ The given cubic (represented in parametric form) is entered in the current path.
.enterspline <x0><y0><x1><y1> ... <xn><yn><n> b õ Creates an open ended curve through the n given points and enters it in the current path. This curve is a natural spline consisting of n cubics.
.entercspline <x0><y0><x1><y1> ... <xn><yn><n> b õ This is the same as enterspline, except a closed curve is formed.
spline <i> b õ This command from the file graphics.jam is equivalent to .enterspline except the i points come from i calls to the .touch function (see below).
cspline <i> b õ This command from the file graphics.jam is equivalent to spline except a closed curve is formed.
.newboundary b õ A new boundary is started on the current path. If the new part of the path is inside a previous boundary in the same path, it designates a hole in the center exactly when it winds in the opposite direction.
.drawarea b õ Fill the interior of the boundaries comprising the current path. The current path is then deleted.
.drawscreenarea b õ Fill in the whole screen using the current texture and painting function.
.erase .erase b õ Erase all area inside the current clipping regions.
.cliparea b õ Set the clipping region to the interiors of the boundaries comprising the current path.
.clippedcliparea .clippedcliparea b õ Set the clipping region equal to its intersection with the interiors of the boundaries comprising the current path
clip <i> b õ Start a new polygonal path defined by i calls to the .touch function (described below) and make this the current clipping region (from graphics.jam).
cclip <i> b õ Execute the clip command except use the intersection of the new region with the old clipping region (from graphics.jam).
clips <i> b õ The new clipping region is the union of i rectangles each defined by to calls to .touch (see below). Each rectangle is defined by two .touch's: one at its lower left corner and the other at its upper right.
blob <i> b õ Start a new path and enter a closed spline defined by i .touch's (like cspline) and fill it in using .drawarea (from graphics.jam).
cblob <i> b õ Draw a blob defined by i .touch's as the blob command does except intersect it with the current clipping region (from graphics.jam).
poly <i> b õ Draw a polygonal line defined by i calls to the .touch function (from graphics.jam).
.dot <x><y> b õ Put down a dot at the coordinates specified.
dot <x><y> b <x><y> õ This command from graphics.jam is like .dot except it copies its arguments.
area <i> b õ Fills in polygonal area defined by i calls to .touch, putting a dot at each .touch (from graphics.jam).
.texture <n> b õ The integer n is viewed as a sixteen bit octal number. It defines a 4 4 bit pattern which is tessellated when filling in areas. By default, n=—1 is used. This causes areas to be filled in solid black.
.paint <n> b õ This function interacts with the .texture setting to determine how pixels are reset when filling in areas. The integer n is in the range 0...3, but is more convenient to use the identifiers defined in the file graphics.jam. Pixels for which the texture bit is 1 are: set to 1 (black) if n=0 (paint), inverted if n=1 (invert), set to 1 and all other pixels are set to 0 if n=2 (replace), and set to 0 (white) if n=3 (erase). The default is paint.
.touch b <x><y> õ Returns the current corrdinates of the mouse when the red'' button is pushed. Execution is halted while waiting for the user to push the button.
.mouse b <x><y> õ Returns the current coordinates of the mouse in the current coordinate system. Execution does not halt. No buttons need be pushed.
.redup b õ This is a user definable function which is executed every time the red'' mouse button is released. When this happens, execution is interrupted and the coordinates of the mouse are put on top of the stack. Then the function executed. All of these default to .pop .pop so they originally function as no-ops.
.reddown b õ similar comment
.yellowup b õ similar comment
.yellowdown b õ similar comment
.blueup b õ similar comment
.bluedown b õ similar comment
.setfont <KS-fontfile name><n> b õ Set the font for the character drawing commands, using n point type. There is no default font, so this command is required before any characters can be drawn.
.drawchar <c> b õ Draw a character at the current draw position and update the draw position to reflect the width of the character.
.erasechar b õ Erase a character at the current draw position and update the draw position by the negative of the width of the character.
.drawstring <s> b õ Draw the string s at the current draw position and update the draw position to reflect the length of the string.
.getstringbox <s> b <x0><y0><x1><y1><x2><y2><x3><y3> õ Return the four corners or the bounding box of the given string.
.getcharbox <c> b <x0><y0><x1><y1><x2><y2><x3><y3> õ Return the four corners or the bounding box of the given character.
text <x><y><dy><s> b õ Put the lines of text from the string s into the screen starting at the point (x,y). Lines are separated by carriage returns and are spaced dy below each other with a left margin at x (from graphics.jam).
.displayoff b õ Blank out the whole screen including the text window.
.displayon b õ Reverse the effect of the previous command.