english
version "1.0"
identify "xyz"

module surface

#: This module generates simulated mountains.

define colors			#: Various colors to use
    record
	line_color xlib_color	#: The color of lines
	mountain_colors vector[xlib_color] #: The moutain colors
	tunnel_color xlib_color	#: The color of the tunnels
	track_color xlib_color	#: The color of train track
	slope_color xlib_color	#: The color of sloped track roadbed
    generate address_get, allocate, erase, identical, print

define roadbed			#: A track roadbed object
    record
	kind roadbed_kind	#: Kind of roadbed
	floor float		#: Floor height of roadbed
	roof float		#: Roof height of roadbed
    generate address_get, allocate, erase, print

define roadbed_kind		#: Various kinds of roadbed
    enumeration
	exposed			#: Exposed roadbed that is visible (floor)
	channel			#: Roadbed channeling into terrain (floor)
	tunnel			#: Plain tunnel with no access (floor & roof)
	tunnel_sideways		#: Side access gap (floor & roof)
	tunnel_down		#: Floor access gap (roof)
    generate equal, print

define elevation		#: One point on the surface.
    record
	height float		#: Height (Z)
	roadbeds vector[roadbed] #: Roadbed heights or ??@{vector}[{roadbed}]
    generate address_get, allocate, erase, print


define scale			#: Stepper scales
    record
	stepper stepper		#: Stepper motor controller object
	x_delta integer		#: Number of steps in X direction to maximum
	x_last integer		#: Last value for X
	x_minimum integer	#: Stepper motor X minimum
	x_millimeters integer	#: Millimters traversed between min. and max.
	y_delta integer		#: Number of steps in y direction to maximum
	y_last integer		#: Last value for Y
	y_millimeters integer	#: Millimters traversed between min. and max.
	y_minimum integer	#: Stepper motor Y minimum
	z_delta float		#: Number of steps in Z direction to maximum
	z_last integer		#: Last value for Z
	z_millimeters float	#: Millimters traversed between min. and max.
	z_minimum integer	#: Stepper motor Z minimum
    generate allocate, erase, print

define surface			#: Surface to be modeled.
    record
	bottom_plane float	#: Height of bottom cut-off plane
	computed logical	#: {true}=>surface computed
	debug_stream out_stream	#: Debugging stream
	grid_size unsigned	#: Number of points in display grid
	span unsigned		#: Distance between elements
	power unsigned		#: Power of 2 for size of grid edge (plus 1)
	rows vector[vector[elevation]]	#: Rows of elevation data.
	top_plane float		#: Height of top cut-off plane
	track_drawn logical	#: {true}=> track drawn
	roadbeds_empty vector[roadbed] #: Empty roadbeds (??@{vector[roadbed]}
	x_offset unsigned	#: Offset to left-most element in display
	x_smooths vector[float]	#: Smoothing vector for x
	y_offset unsigned	#: Offset to left_most element in display
	y_smooths vector[float]	#: Smoothing vector for y
    generate address_get, allocate, erase, identical, print


define random			#: Random number generator.
    record
	arand unsigned		#: Random number is between [0, arand]
	denominator float	#: Denominator for adjustment
	four float		#: The constant 4.0
	gauss_add float		#: Gaussian adjustment?
	nrand unsigned		#: Number of times to call random number gen.
	numerator float		#: Numerator for adjustment
	out_stream out_stream
	three float		#: The constant 3.0
    generate allocate, erase, print



#: {colors} procedures:

procedure create@colors
    takes
	color_map xlib_color_map
    returns colors

    #: This procedure will create and allocate a bunch of colors from
    #, {color_map}.


#: {elevation} procedures:

procedure create@elevation
    takes
	surface surface
    returns elevation

    #: This procedure will allocate and return a new {elevation} object
    #, for location ({x}, {y}).  The object is allocated using {surface}.


procedure points_append@elevation
    takes
	elevation elevation
	points xlib_points
	surface surface
	x_index unsigned
	y_index unsigned
    returns logical

    #: This procedure will append an {xlib_point} to {points} that
    #, corresponds to the elevation information in {elevation}.
    #, {elevation} is located at ({x_index}, {y_index}) in {surface}.
    #, {true}@{logical} is returned if the elevation information is
    #, a "tunnel" and {false} otherwise.


procedure draw@elevation
    takes
	elevation elevation
	surface surface
	drawable xlib_drawable
	gc xlib_gc
	colors colors
	points xlib_points
	x_index unsigned
	y_index unsigned
	last_color xlib_color
    returns xlib_color

    #: This procedure will draw a poloygon that represents {eleavation}
    #, to {drawable}.


procedure roadbed_height_get@elevation
    takes
	elevation elevation
    returns float

    #: This procedure will return the height of the roadbed for {elevation}
    #, or {zero}@{float} if there is no track associated with {elevation}.


procedure roadbed_height_set@elevation
    takes
	elevation elevation
	floor float
    returns_nothing

    #: This procedure will set the height of the roadbed for {elevation}
    #, to {floor}.


procedure z_get@elevation
    takes
	elevation elevation
    returns float

    #: This procedure will return the height of {elevation}.


procedure z_set@elevation
    takes
	elevation elevation
	z float
    returns_nothing

    #: This procedure will set the height of {elevation}.


#: {scale} procedures:

procedure create@scale
    takes
	stepper stepper
    returns scale

    #: This procedure will create and return an empty {scale} object.


procedure goto@scale
    takes
	scale scale
	x unsigned
	y unsigned
	z float
    returns_nothing

    #: This procedure will cause the stepper motors to step to slew
    #, over to ({x}, {y}, {z}) using {scale}.


procedure is_calibrated@scale
    takes
	scale scale
    returns logical

    #: This procedure will return {true}@{logical} if X, Y, and Z axises
    #, of {scale} have all been calibrated.


procedure origin@scale
    takes
	scale scale
    returns_nothing

    #: This procedure will set the orgin for {scale}.


procedure x_calibrate@scale
    takes
	scale scale
	x_millimeters unsigned
    returns_nothing

    #: This procedure callibrates X direction for {scale}.


procedure y_calibrate@scale
    takes
	scale scale
	y_millimeters unsigned
    returns_nothing

    #: This procedure callibrates Y direction for {scale}.


procedure z_calibrate@scale
    takes
	scale scale
	z_millimeters unsigned
    returns_nothing

    #: This procedure callibrates X direction for {scale}.


#: {surface} procedures:

procedure absolute@surface
    takes
	surface surface
    returns_nothing

    #: This procedure will perform the absolute operation on each
    #, height in {surface}.


procedure add@surface
    takes
	to_surface surface
	from_surface surface
    returns_nothing

    #: This procedure will add {from_surface} to {to_surface}.  The
    #, surfaces must be of the same size.


procedure clear@surface
    takes
	surface surface
    returns_nothing

    #: This procedure will "flatten" {surface}.


procedure create@surface
    takes
	power unsigned
	x_pixels unsigned
	y_pixels unsigned
	debug_stream out_stream
    returns surface

    #: This procedure will create and return a new {surface} object.
    #, The underlying grid will be 2 to the {power} cells along each
    #, edge.  {x_pixels} specifies the distance between x pixels and
    #, {y_pixels} specifies the distance between y pixels.


procedure draw@surface
    takes
	surface surface
	drawable xlib_drawable
	gc xlib_gc
	colors colors
	points xlib_points
	debug_stream out_stream
    returns_nothing

    #: This procedure will draw {surface} to {drawable}.


procedure goto@surface
    takes
	surface surface
	scale scale
	x unsigned
	y unsigned
	lift_first logical
    returns_nothing

    #: This procedure will move the sculpting tip to ({x}, {y})) on
    #, {surface}.  If {lift_first} is {true}, the sculpting tip is
    #, lifted above the surface before being moved; otherwise, the
    #, sculpting tip is moved in a linear fashion.


procedure fetch2@surface
    takes
	surface surface
	x unsigned
	y unsigned
    returns elevation

    #: This procedure will return the {elevation} object corresponding
    #, to ({x}, {y}).


procedure generate@surface
    takes
	surface surface
	sigma float
	h float
	addition logical
	random random
	debug_stream out_stream
    returns_nothing

    #: This procedure will produce a mountain contour for {surface}
    #, using {sigma}, {h}, and {random} to control the entire process.
	

procedure minus@surface
    takes
	surface surface
    returns_nothing

    #: This procedure will perform the minus operation on each
    #, height in {surface}


procedure read@surface
    takes
	surface surface
	in_stream in_stream
	debug_stream out_stream
    returns_nothing

    #: This procedure will read in {surface} from {in_stream}.


procedure scale_in@surface
    takes
	to_surface surface
	from_surface surface
	scale float
    returns_nothing

    #: This procedure will extract region from {from_surface} that
    #, corresponds to the currently displayed region in {to_surface},
    #, multiply it by {scale} and add it into {to_surface}.  There is
    #, smoothing near the edges to hide any edge effects.


procedure sculpt@surface
    takes
	surface surface
	scale scale
    returns_nothing

    #: This procedure will cause the stepper motors controlled by {scale}
    #, to sculpt some styrofoam to look like {surface}.


procedure track_extract@surface
    takes
	to_surface surface
	from_surface surface
    returns_nothing

    #: This procedure will extract the track elevations from {from_surface}
    #, and insert them into {to_surface}.  The  surfaces must be of the
    #, same size.


procedure write@surface
    takes
	surface surface
	out_stream out_stream
	debug_stream out_stream
    returns_nothing

    #: This procedure will write {surface} out to {out_stream}.


#: {random} procedures:

procedure create@random
    takes
	seed unsigned
	out_stream out_stream
    returns random

    #: This procedure will return a new random number generator.


procedure gauss@random
    takes
	random random
    returns float

    #: Returns a gaussian random number.


procedure f3
    takes
	delta float
	x0 float
	x1 float
	x2 float
	random random
    returns float


procedure f4
    takes
	delta float
	x0 float
	x1 float
	x2 float
	x3 float
	random random
    returns float


procedure unsigned_append@xlib_points
    takes
	points xlib_points
	x unsigned
	y unsigned
    returns_nothing

    #: This procedure append ({x}, {y}) to {points}.


#: {roadbed} routines:

procedure create@roadbed
    takes
	kind roadbed_kind
	floor float
	roof float
    returns roadbed

    #, type {kind} that contains {floor} and {roof}.


procedure compare@roadbed
    takes
	roadbed1 roadbed
	roadbed2 roadbed
    returns integer

    #: This procedure will return -1, 0, or 1 depending upon whether
    #, {roadbed1} is less than, equal to, or greater than {roadbed2}.